@koobiq/components 20.4.1 → 21.0.0

package/types/koobiq-components-splitter.d.ts

@@ -0,0 +1,406 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, InputSignal, ModelSignal, Provider } from '@angular/core';
+import * as i1 from '@koobiq/components/resizer';
+import { KbqResizerDirection, KbqResizerSizeChangeEvent } from '@koobiq/components/resizer';
+
+/** Direction the panels of a splitter are laid out in. */
+type KbqSplitterOrientation = 'horizontal' | 'vertical';
+/**
+ * How a splitter draws its separators.
+ *
+ * - `divider` — a line between the panels, the default.
+ * - `transparent` — nothing until the pointer reaches the separator, which then gives itself away by the cursor.
+ * - `handle` — a grip centred on the boundary.
+ */
+type KbqSplitterAppearance = 'divider' | 'transparent' | 'handle';
+/**
+ * Size of a splitter panel: a number of pixels, a `<number>px` string, or a `<number>%` share of the
+ * splitter's own size along the resize axis. A size in any other unit is ignored.
+ */
+type KbqSplitterSize = number | string;
+/**
+ * Moves the boundary that follows `index` by `delta` pixels and returns the new sizes.
+ *
+ * The panels on one side of the boundary take the delta and the ones on the other side give it up, each walking
+ * outwards from the boundary: a panel sitting at its limit hands the remainder to the next one instead of
+ * stopping the drag. Walking outwards on the taking side too is what keeps a boundary reachable when the panel
+ * right beside it is pinned — otherwise a neighbour at its maximum would freeze a boundary that the panels
+ * further out could still move, and the drag would do nothing at all.
+ */
+declare function resizeSplitterSizesAt(sizes: readonly number[], index: number, delta: number, min: readonly number[], max: readonly number[]): number[];
+/** A size a drag is pulled onto, with the distance the release has to be within for the pull to happen. */
+type KbqSplitterSnapPoint = {
+    size: number;
+    tolerance: number;
+};
+/**
+ * Settings a whole application shares, rather than something a single splitter decides.
+ *
+ * Only what a product picks once belongs here: how its separators look, and how far a snap size reaches. The
+ * sizes and limits of the panels are a property of one layout and stay on the panels themselves.
+ */
+type KbqSplitterOptions = {
+    /** How the separators are drawn. */
+    appearance: KbqSplitterAppearance;
+    /** How close to a snap size a drag has to be released for it to be pulled in, in pixels. */
+    snapTolerance: number;
+};
+/** Injection token holding the current {@link KbqSplitterOptions}. */
+declare const KBQ_SPLITTER_OPTIONS: InjectionToken<KbqSplitterOptions>;
+/**
+ * Overrides the default splitter options within the given injector scope — the whole application from
+ * `bootstrapApplication`, or one subtree from the `providers` of a component or a route.
+ */
+declare function kbqSplitterOptionsProvider(options: Partial<KbqSplitterOptions>): Provider;
+/**
+ * The part of a panel that its splitter and its own separator read.
+ *
+ * @docs-private
+ */
+interface KbqSplitterPanelRef {
+    readonly id: Signal<string>;
+    readonly element: HTMLElement;
+    readonly size: InputSignal<KbqSplitterSize | undefined>;
+    readonly minSize: InputSignal<KbqSplitterSize | undefined>;
+    readonly maxSize: InputSignal<KbqSplitterSize | undefined>;
+    readonly snapSizes: InputSignal<readonly KbqSplitterSize[]>;
+    readonly snapTolerance: Signal<number>;
+    readonly collapsible: Signal<boolean>;
+    readonly collapsedSize: InputSignal<KbqSplitterSize>;
+    readonly collapsed: ModelSignal<boolean>;
+}
+/**
+ * The part of a splitter its panels read. Panels are projected content, so they reach the group through this
+ * token rather than through its class.
+ *
+ * @docs-private
+ */
+interface KbqSplitterGroup {
+    readonly orientation: Signal<KbqSplitterOrientation>;
+    readonly disabled: Signal<boolean>;
+    readonly panels: Signal<readonly KbqSplitterPanelRef[]>;
+    /** Direction the separator of the panel at `index` resizes in; `[0, 0]` while the splitter is disabled. */
+    readonly resizerDirection: Signal<KbqResizerDirection>;
+    /** Cursor for the separator of the panel at `index`, reflecting the room its boundary still has. */
+    separatorCursor(index: number): string;
+    /** `aria-valuenow` / `aria-valuemin` / `aria-valuemax` of the separator, as percentages of the splitter. */
+    separatorValues(index: number): {
+        now: number;
+        min: number;
+        max: number;
+    };
+    /** `origin` is the size the drag measures its travel from; the panel's own size when omitted. */
+    handleResizeStart(index: number, origin?: number): void;
+    handleResizeTo(index: number, size: number): void;
+    handleResizeEnd(): void;
+    handleSeparatorKeydown(index: number, event: KeyboardEvent): void;
+    handleSeparatorDblClick(index: number): void;
+}
+/**
+ * Contract a {@link KbqSplitterPanel} resolves to reach the splitter that projects it.
+ *
+ * @docs-private
+ */
+declare const KBQ_SPLITTER: InjectionToken<KbqSplitterGroup>;
+/**
+ * A resizable region of a {@link KbqSplitter}.
+ *
+ * Every panel but the last renders the separator that follows it, so the separator sits between the two
+ * panels it resizes in the tab order as well as on screen.
+ */
+declare class KbqSplitterPanel implements KbqSplitterPanelRef {
+    /** @docs-private */
+    protected readonly splitter: KbqSplitterGroup;
+    private readonly options;
+    private readonly focusMonitor;
+    private readonly a11yLocaleConfiguration;
+    /** @docs-private */
+    readonly element: HTMLElement;
+    /**
+     * Identifies the panel to the `aria-controls` of its own separator, and gives a host something to point
+     * `aria-labelledby` or a fragment link at. Generated when omitted.
+     */
+    readonly id: InputSignal<string>;
+    /**
+     * Size the panel starts at, in pixels (`240`, `'240px'`) or as a share of the splitter (`'30%'`).
+     * Panels that leave it unset share whatever the sized ones did not claim.
+     */
+    readonly size: InputSignal<KbqSplitterSize | undefined>;
+    /** Smallest size the panel may be dragged to. Defaults to `0`. */
+    readonly minSize: InputSignal<KbqSplitterSize | undefined>;
+    /** Largest size the panel may be dragged to. Unbounded when omitted. */
+    readonly maxSize: InputSignal<KbqSplitterSize | undefined>;
+    /**
+     * Sizes a drag is pulled onto when it is released near one. `minSize` and `maxSize` become snap points too
+     * as soon as either panel around a separator declares any snap size.
+     *
+     * The layout the panels start at settles onto them as well, so a splitter is never handed to the user
+     * sitting between two of its own snap points.
+     */
+    readonly snapSizes: InputSignal<readonly KbqSplitterSize[]>;
+    /**
+     * How close to one of this panel's {@link snapSizes} a drag has to be released for it to be pulled in, in
+     * pixels. Raise it to make the snap points reach further — past half the gap between two of them the panel
+     * can only ever land on a snap size.
+     *
+     * Defaults to the app-wide {@link KBQ_SPLITTER_OPTIONS}.
+     */
+    readonly snapTolerance: i0.InputSignalWithTransform<number, unknown>;
+    /**
+     * Whether dragging the panel past half of its `minSize` collapses it to `collapsedSize` instead of
+     * stopping at the minimum.
+     */
+    readonly collapsible: i0.InputSignalWithTransform<boolean, unknown>;
+    /** Size the panel takes while collapsed. `0` — the default — hides it completely. */
+    readonly collapsedSize: InputSignal<KbqSplitterSize>;
+    /**
+     * Whether the panel is collapsed. Two-way, so a host can collapse and restore the panel itself — which is
+     * the only way back for a panel whose `collapsedSize` is `0` and which therefore has no separator to grab.
+     */
+    readonly collapsed: ModelSignal<boolean>;
+    /** Accessible name of the separator that follows the panel; falls back to the localized default. */
+    readonly separatorAriaLabel: InputSignal<string | undefined>;
+    /** The panel's own separator; a subtree search would find a nested splitter's separators first. */
+    private readonly separator;
+    /** @docs-private */
+    protected readonly index: Signal<number>;
+    /**
+     * Whether the panel renders no separator. The last panel has nothing after it to resize against, and a
+     * panel that reached the splitter through the element injector without being one of its content children —
+     * a wrapper element or another component's template stands between them — has no place in the group at
+     * all, so it must not offer a handle whose ARIA values would resolve against an index of `-1`.
+     *
+     * @docs-private
+     */
+    protected readonly last: Signal<boolean>;
+    /** @docs-private */
+    protected readonly disabled: Signal<boolean>;
+    /** A separator is oriented across the axis its splitter lays panels out along. @docs-private */
+    protected readonly separatorOrientation: Signal<"horizontal" | "vertical">;
+    /** @docs-private */
+    protected readonly separatorCursor: Signal<string>;
+    /** @docs-private */
+    protected readonly separatorValues: Signal<{
+        now: number;
+        min: number;
+        max: number;
+    }>;
+    /** @docs-private */
+    protected readonly resolvedSeparatorAriaLabel: Signal<string>;
+    /** Unsupported sizes already reported, so a check that runs again does not repeat itself. */
+    private readonly reportedSizes;
+    constructor();
+    /**
+     * Demotes the separator's focus origin to the pointer when a drag starts, so the keyboard-focus frame
+     * stays hidden for the whole drag and does not linger afterwards. Keyboard focus keeps the frame.
+     *
+     * `preventScroll` because half of the separator reaches past the panel it belongs to: once the panel beyond
+     * it is collapsed to nothing, that half hangs outside the splitter itself, and revealing it would scroll
+     * whatever clipping box the splitter sits in — leaving the panels shifted by half a hit area, with a blank
+     * strip along the edge that nothing scrolls back.
+     *
+     * @docs-private
+     */
+    protected handleResizeStart({ width, height }: KbqResizerSizeChangeEvent): void;
+    /** @docs-private */
+    protected handleSizeChange({ width, height }: KbqResizerSizeChangeEvent): void;
+    /** @docs-private */
+    protected handleSeparatorKeydown(event: KeyboardEvent): void;
+    /** @docs-private */
+    protected handleSeparatorDblClick(event: MouseEvent): void;
+    private reportUnsupportedSizes;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqSplitterPanel, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqSplitterPanel, "kbq-splitter-panel", ["kbqSplitterPanel"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "minSize": { "alias": "minSize"; "required": false; "isSignal": true; }; "maxSize": { "alias": "maxSize"; "required": false; "isSignal": true; }; "snapSizes": { "alias": "snapSizes"; "required": false; "isSignal": true; }; "snapTolerance": { "alias": "snapTolerance"; "required": false; "isSignal": true; }; "collapsible": { "alias": "collapsible"; "required": false; "isSignal": true; }; "collapsedSize": { "alias": "collapsedSize"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "separatorAriaLabel": { "alias": "separatorAriaLabel"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; }, never, ["*"], true, [{ directive: typeof i1.KbqResizable; inputs: {}; outputs: {}; }]>;
+}
+/**
+ * Splits an area into panels the user can resize by dragging the separators between them.
+ *
+ * Panels must be direct children of the splitter — a wrapper element around them hides them from the group.
+ *
+ * @example
+ * ```html
+ * <kbq-splitter>
+ *     <kbq-splitter-panel [minSize]="100">…</kbq-splitter-panel>
+ *     <kbq-splitter-panel>…</kbq-splitter-panel>
+ * </kbq-splitter>
+ * ```
+ */
+declare class KbqSplitter implements KbqSplitterGroup {
+    private readonly nativeElement;
+    private readonly destroyRef;
+    private readonly platform;
+    private readonly window;
+    private readonly resizeObserver;
+    private readonly directionality;
+    private readonly options;
+    /** Direction the panels are laid out in. */
+    readonly orientation: InputSignal<KbqSplitterOrientation>;
+    /** How the separators are drawn. Defaults to the app-wide {@link KBQ_SPLITTER_OPTIONS}. */
+    readonly appearance: InputSignal<KbqSplitterAppearance>;
+    /** Whether the panels can be resized at all. */
+    readonly disabled: i0.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Sizes of the panels as percentages of the splitter, in panel order.
+     *
+     * Two-way and, while `null`, derived from what the panels declare — so a host reads it to persist a
+     * layout, writes it to restore one, and shares the same signal between two splitters to keep their panels
+     * the same width. Setting it back to `null` returns the panels to their declared sizes.
+     */
+    readonly layout: ModelSignal<number[] | null>;
+    /** @docs-private */
+    readonly panels: Signal<readonly KbqSplitterPanel[]>;
+    /** Boundary a drag is moving right now, or `null` when no drag is in progress. */
+    private readonly dragBoundary;
+    /** Whether a separator is being dragged right now. @docs-private */
+    protected readonly dragging: Signal<boolean>;
+    /** Splitter size along the resize axis, in pixels; `0` until the first measurement. */
+    private readonly containerSize;
+    /** Sizes and layout captured when the drag began; every move is measured against these, so clamping cannot drift. */
+    private dragSnapshot;
+    private readonly rtl;
+    /** A disabled splitter reports no direction, which is how `KbqResizer` ignores a drag. @docs-private */
+    readonly resizerDirection: Signal<KbqResizerDirection>;
+    /** Smallest size of each panel while it is not collapsed, in pixels. */
+    private readonly expandedMinSizes;
+    /** Largest size of each panel while it is not collapsed, in pixels. */
+    private readonly expandedMaxSizes;
+    /** Size a collapsed panel is pinned to, in pixels. */
+    private readonly collapsedSizes;
+    /**
+     * Panels the drag in progress may take through the gap between their collapsed size and their minimum.
+     *
+     * Only the two around the boundary being dragged. A collapsible panel further out is being pushed rather
+     * than aimed at, and letting a push carry one into its gap would collapse it without the user ever having
+     * pointed at it.
+     */
+    private readonly freePanels;
+    /**
+     * Smallest size of each panel in pixels; a collapsed panel is pinned to its collapsed size.
+     *
+     * The sizes a collapsible panel may take are its collapsed size and everything from its minimum up, with a
+     * gap in between that it never occupies. Pinning it by `collapsed` is what keeps a drag out of that gap: the
+     * panel stops at the minimum and waits there while the pointer crosses, and `collapsed` flips it to the strip
+     * once the pointer passes the midpoint.
+     */
+    private readonly minSizes;
+    /** Largest size of each panel in pixels; a collapsed panel is pinned to its collapsed size. */
+    private readonly maxSizes;
+    /** Sizes seeded from what the panels declare — where the splitter starts and what a reset returns to. */
+    private readonly defaultSizes;
+    /** Current size of every panel in pixels. */
+    private readonly sizes;
+    /**
+     * Tracks are percentages of the splitter's content box, which is exactly what `containerSize` measures, so
+     * `size / total` renders as `size` pixels whatever padding the host puts on the splitter.
+     *
+     * Not `fr`: a flex factor carries only a ratio, and CSS Grid normalizes the factors by their sum. Sizes
+     * that cannot add up to the container — every panel pinned to a minimum too large to fit, or every panel
+     * capped below it — would then be silently rescaled to fill it, violating the very `minSize`/`maxSize` the
+     * layout was computed from, while `aria-valuenow` and the drag arithmetic went on reporting the sizes the
+     * component believed it had applied. Percentages under- or overflow instead, which is visible.
+     *
+     * Equal tracks stand in until the first measurement, which is the only layout that cannot be wrong before
+     * the splitter has a size to resolve `%` and `px` against.
+     *
+     * @docs-private
+     */
+    protected readonly gridTemplate: Signal<string | null>;
+    constructor();
+    /** @docs-private */
+    separatorCursor(index: number): string;
+    /** @docs-private */
+    separatorValues(index: number): {
+        now: number;
+        min: number;
+        max: number;
+    };
+    /** @docs-private */
+    handleResizeStart(index: number, origin?: number): void;
+    /** @docs-private */
+    handleResizeTo(index: number, size: number): void;
+    /** @docs-private */
+    handleResizeEnd(): void;
+    /** @docs-private */
+    handleSeparatorKeydown(index: number, event: KeyboardEvent): void;
+    /** @docs-private */
+    handleSeparatorDblClick(index: number): void;
+    /**
+     * Whether the panels are still the ones the drag was measured against.
+     *
+     * A host that adds or removes a panel mid-drag invalidates every index the snapshot holds: the captured
+     * sizes stop lining up with `minSizes`/`maxSizes`, which turns the arithmetic into `NaN`, and a boundary
+     * index no longer names the panel the user took hold of.
+     */
+    private matchesSnapshot;
+    private commitKeydown;
+    /** Moves focus onto a panel, which is how `F6` walks the regions of the splitter. */
+    private focusPanel;
+    /**
+     * Room on each side of the boundary after `index`, in pixels.
+     *
+     * Measured against the expanded limits rather than the collapse pin, because a collapsed panel can still be
+     * dragged back out — reporting it as immovable would leave the cursor saying otherwise.
+     */
+    private sideRoom;
+    /**
+     * How far the boundary after `index` can still travel each way — what the cursor advertises.
+     *
+     * Both sides are summed across every panel, because the drag walks outwards from the boundary: a neighbour
+     * pinned at its limit passes the delta on, so the boundary is still movable when it alone is stuck.
+     */
+    private boundaryRoom;
+    /**
+     * How far the panel at `index` itself can still be resized — what `aria-valuemin` / `aria-valuemax` report.
+     *
+     * Narrower than {@link boundaryRoom} on purpose: the boundary may keep moving by handing the delta to panels
+     * further out, and those moves leave the pane this separator controls exactly where it was.
+     */
+    private panelRoom;
+    private resizeBy;
+    /**
+     * Settles a seeded layout onto the snap points its panels declare, boundary by boundary, exactly as
+     * releasing a drag on each of them would.
+     *
+     * Only the seeded sizes go through this. A layout handed to the splitter is authoritative — settling that
+     * one would both overwrite a restored layout and pull the boundary onto a point mid-drag, since every move
+     * writes `layout`.
+     */
+    private settleOnSnapPoints;
+    /** Pulls the drag onto the nearest snap point declared by either panel around the separator. */
+    private snapDelta;
+    /**
+     * Which side of its gap each panel around the dragged boundary is held on.
+     *
+     * Decided from the size the pointer is asking for rather than the one on screen, because a panel held at
+     * its minimum or on its collapsed strip has stopped moving — only where the pointer went says what the user
+     * means. Half the minimum is the midpoint of the gap, so the same distance decides the panel whichever
+     * direction it came from.
+     */
+    private pinsFor;
+    /** Clears the drag, so the panels go back to their settled limits. */
+    private endDrag;
+    /**
+     * Hands every collapsible panel around the boundary that ended the drag collapsed the share it had before the
+     * gesture. `collapsed` itself already changed during the drag; only the size it returns to is left to fix.
+     *
+     * Returns whether anything is collapsed.
+     */
+    private settleCollapse;
+    private applySizes;
+    private measure;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqSplitter, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqSplitter, "kbq-splitter", ["kbqSplitter"], { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "layout": { "alias": "layout"; "required": false; "isSignal": true; }; }, { "layout": "layoutChange"; }, ["panels"], ["*"], true, never>;
+}
+
+/**
+ * Convenience module for `NgModule` consumers. Everything it re-exports is standalone, so importing
+ * `KbqSplitter` and `KbqSplitterPanel` directly is the preferred way in — the library's own examples do that.
+ */
+declare class KbqSplitterModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqSplitterModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqSplitterModule, never, [typeof KbqSplitter, typeof KbqSplitterPanel], [typeof KbqSplitter, typeof KbqSplitterPanel]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<KbqSplitterModule>;
+}
+
+export { KBQ_SPLITTER, KBQ_SPLITTER_OPTIONS, KbqSplitter, KbqSplitterModule, KbqSplitterPanel, kbqSplitterOptionsProvider, resizeSplitterSizesAt };
+export type { KbqSplitterAppearance, KbqSplitterGroup, KbqSplitterOptions, KbqSplitterOrientation, KbqSplitterPanelRef, KbqSplitterSize, KbqSplitterSnapPoint };

package/types/koobiq-components-table.d.ts

@@ -0,0 +1,44 @@
+import * as i0 from '@angular/core';
+
+/**
+ * A styling layer over a native `<table>`: it applies the library's spacing, typography and colors and
+ * leaves the semantics to the platform. Sorting, resizing and virtual scrolling are out of scope — only
+ * standard HTML table capabilities are available.
+ */
+declare class KbqTable {
+    private readonly elementRef;
+    private readonly resizeObserver;
+    private readonly platform;
+    /**
+     * Whether a line is drawn under every body row. Toggles the `kbq-table_bordered` class. Defaults to `false`.
+     */
+    readonly border: i0.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether the background change on row hover is suppressed. Toggles the `kbq-table_disable-hover`
+     * class. Use it when rows are not interactive and the highlight would be misleading. Defaults to `false`.
+     */
+    readonly disableHover: i0.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether the header stays visible while the table scrolls. Toggles the `kbq-table_sticky-header`
+     * class. Defaults to `false`.
+     */
+    readonly stickyHeader: i0.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Measured height of the pinned header, published as `--kbq-table-size-sticky-header-height`. Body
+     * cells and the focusable content inside them use it as `scroll-margin-block-start`, so scrolling a
+     * control into view does not leave it under the header (WCAG 2.2 SC 2.4.11).
+     */
+    protected readonly stickyHeaderHeight: i0.WritableSignal<number | null>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqTable, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqTable, "table[kbq-table]", ["kbqTable"], { "border": { "alias": "border"; "required": false; "isSignal": true; }; "disableHover": { "alias": "disableHover"; "required": false; "isSignal": true; }; "stickyHeader": { "alias": "stickyHeader"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+/** Legacy entry point for `KbqTable`. Standalone consumers import `KbqTable` directly. */
+declare class KbqTableModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<KbqTableModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqTableModule, never, [typeof KbqTable], [typeof KbqTable]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<KbqTableModule>;
+}
+
+export { KbqTable, KbqTableModule };