@cute-widgets/base 20.0.1

package/grid-list/index.d.ts

@@ -0,0 +1,361 @@
+import * as i0 from '@angular/core';
+import { AfterContentInit, QueryList, OnInit, AfterContentChecked } from '@angular/core';
+import * as i2 from '@cute-widgets/base/core';
+import { CuteLine } from '@cute-widgets/base/core';
+import { NumberInput } from '@angular/cdk/coercion';
+import * as i1 from '@angular/common';
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+/**
+ * Base interface for a `CuteGridList`.
+ */
+interface CuteGridListBase {
+    cols: number;
+    gutterSize: string;
+    rowHeight: number | string;
+}
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+declare class CuteGridTile {
+    private _element;
+    _gridList?: CuteGridListBase | null | undefined;
+    _rowspan: number;
+    _colspan: number;
+    constructor(...args: unknown[]);
+    /** Number of rows that the grid tile takes up. */
+    get rowspan(): number;
+    set rowspan(value: NumberInput);
+    /** Number of columns that the grid tile takes up. */
+    get colspan(): number;
+    set colspan(value: NumberInput);
+    /**
+     * Sets the style of the grid-tile element.  Needs to be set manually to avoid
+     * "Changed after checked" errors that would occur with HostBinding.
+     */
+    _setStyle(property: string, value: any): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridTile, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CuteGridTile, "cute-grid-tile", ["cuteGridTile"], { "rowspan": { "alias": "rowspan"; "required": false; }; "colspan": { "alias": "colspan"; "required": false; }; }, {}, never, ["*"], true, never>;
+}
+declare class CuteGridTileText implements AfterContentInit {
+    private _element;
+    _lines: QueryList<CuteLine> | undefined;
+    constructor(...args: unknown[]);
+    ngAfterContentInit(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridTileText, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CuteGridTileText, "cute-grid-tile-header, cute-grid-tile-footer", never, {}, {}, ["_lines"], ["[cute-grid-avatar], [cuteGridAvatar]", "[cute-line], [cuteLine]", "*"], true, never>;
+}
+/**
+ * Directive whose purpose is to add the `cute-` CSS styling to this selector.
+ */
+declare class CuteGridAvatarCssCuteStyler {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridAvatarCssCuteStyler, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CuteGridAvatarCssCuteStyler, "[cute-grid-avatar], [cuteGridAvatar]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Directive whose purpose is to add the `cute-` CSS styling to this selector.
+ */
+declare class CuteGridTileHeaderCssCuteStyler {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridTileHeaderCssCuteStyler, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CuteGridTileHeaderCssCuteStyler, "cute-grid-tile-header", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Directive whose purpose is to add the `cute-` CSS styling to this selector.
+ */
+declare class CuteGridTileFooterCssCuteStyler {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridTileFooterCssCuteStyler, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CuteGridTileFooterCssCuteStyler, "cute-grid-tile-footer", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Interface describing a tile.
+ */
+interface Tile {
+    /** Number of rows that the tile takes up. */
+    rowspan: number;
+    /** Number of columns that the tile takes up. */
+    colspan: number;
+}
+/**
+ * Class for determining, from a list of tiles, the (row, col) position of each of those tiles
+ * in the grid. This is necessary (rather than just rendering the tiles in normal document flow)
+ * because the tiles can have a rowspan.
+ *
+ * The positioning algorithm greedily places each tile as soon as it encounters a gap in the grid
+ * large enough to accommodate it so that the tiles still render in the same order in which they
+ * are given.
+ *
+ * The basis of the algorithm is the use of an array to track the already placed tiles. Each
+ * element of the array corresponds to a column, and the value indicates how many cells in that
+ * column are already occupied; zero indicates an empty cell. Moving "down" to the next row
+ * decrements each value in the tracking array (indicating that the column is one cell closer to
+ * being free).
+ */
+declare class TileCoordinator {
+    /** Tracking array (see class description). */
+    tracker: number[];
+    /** Index at which the search for the next gap will start. */
+    columnIndex: number;
+    /** The current row index. */
+    rowIndex: number;
+    /** Gets the total number of rows occupied by tiles */
+    get rowCount(): number;
+    /**
+     * Gets the total span of rows occupied by tiles.
+     * Ex: A list with 1 row that contains a tile with rowspan 2 will have a total rowspan of 2.
+     */
+    get rowspan(): number;
+    /** The computed (row, col) position of each tile (the output). */
+    positions: TilePosition[];
+    /**
+     * Updates the tile positions.
+     * @param numColumns Amount of columns in the grid.
+     * @param tiles Tiles to be positioned.
+     */
+    update(numColumns: number, tiles: Tile[]): void;
+    /** Calculates the row and col position of a tile. */
+    private _trackTile;
+    /** Finds the next available space large enough to fit the tile. */
+    private _findMatchingGap;
+    /** Move "down" to the next row. */
+    private _nextRow;
+    /**
+     * Finds the end index (exclusive) of a gap given the index from which to start looking.
+     * The gap ends when a non-zero value is found.
+     */
+    private _findGapEndIndex;
+    /** Update the tile tracker to account for the given tile in the given space. */
+    private _markTilePosition;
+}
+/**
+ * Simple data structure for tile position (row, col).
+ */
+declare class TilePosition {
+    row: number;
+    col: number;
+    constructor(row: number, col: number);
+}
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+/** Object that can be styled by the `TileStyler`. */
+interface TileStyleTarget {
+    _setListStyle(style: [string, string | null] | null): void;
+    _tiles: QueryList<CuteGridTile>;
+}
+/**
+ * Sets the style properties for an individual tile, given the position calculated by the
+ * Tile Coordinator.
+ */
+declare abstract class TileStyler {
+    _gutterSize: string | undefined;
+    _rows: number;
+    _rowspan: number;
+    _cols: number;
+    _direction: string | undefined;
+    /**
+     * Adds grid-list layout info once it is available. Cannot be processed in the constructor
+     * because these properties haven't been calculated by that point.
+     *
+     * @param gutterSize Size of the grid's gutter.
+     * @param tracker Instance of the TileCoordinator.
+     * @param cols Amount of columns in the grid.
+     * @param direction Layout direction of the grid.
+     */
+    init(gutterSize: string, tracker: TileCoordinator, cols: number, direction: string): void;
+    /**
+     * Computes the amount of space a single 1x1 tile would take up (width or height).
+     * Used as a basis for other calculations.
+     * @param sizePercent Percent of the total grid-list space that one 1x1 tile would take up.
+     * @param gutterFraction Fraction of the gutter size taken up by one 1x1 tile.
+     * @return The size of a 1x1 tile as an expression that can be evaluated via CSS calc().
+     */
+    getBaseTileSize(sizePercent: number, gutterFraction: number): string;
+    /**
+     * Gets the horizontal or vertical position of a tile, e.g., the 'top' or 'left' property value.
+     * @param offset Number of tiles that have already been rendered in the row/column.
+     * @param baseSize Base size of a 1x1 tile (as computed in getBaseTileSize).
+     * @return Position of the tile as a CSS calc() expression.
+     */
+    getTilePosition(baseSize: string, offset: number): string;
+    /**
+     * Gets the actual size of a tile, e.g., width or height, taking rowspan or colspan into account.
+     * @param baseSize Base size of a 1x1 tile (as computed in getBaseTileSize).
+     * @param span The tile's rowspan or colspan.
+     * @return Size of the tile as a CSS calc() expression.
+     */
+    getTileSize(baseSize: string, span: number): string;
+    /**
+     * Sets the style properties to be applied to a tile for the given row and column index.
+     * @param tile Tile to which to apply the styling.
+     * @param rowIndex Index of the tile's row.
+     * @param colIndex Index of the tile's column.
+     */
+    setStyle(tile: CuteGridTile, rowIndex: number, colIndex: number): void;
+    /** Sets the horizontal placement of the tile in the list. */
+    setColStyles(tile: CuteGridTile, colIndex: number, percentWidth: number, gutterWidth: number): void;
+    /**
+     * Calculates the total size taken up by gutters across one axis of a list.
+     */
+    getGutterSpan(): string;
+    /**
+     * Calculates the total size taken up by tiles across one axis of a list.
+     * @param tileHeight Height of the tile.
+     */
+    getTileSpan(tileHeight: string): string;
+    /**
+     * Sets the vertical placement of the tile in the list.
+     * This method will be implemented by each type of TileStyler.
+     * @docs-private
+     */
+    abstract setRowStyles(tile: CuteGridTile, rowIndex: number, percentWidth: number, gutterWidth: number): void;
+    /**
+     * Calculates the computed height and returns the correct style property to set.
+     * This method can be implemented by each type of TileStyler.
+     * @docs-private
+     */
+    getComputedHeight(): [string, string] | null;
+    /**
+     * Called when the tile styler is swapped out with a different one. To be used for cleanup.
+     * @param list Grid list that the styler was attached to.
+     * @docs-private
+     */
+    abstract reset(list: TileStyleTarget): void;
+}
+/**
+ * This type of styler is instantiated when the user passes in a fixed row height.
+ * Example `<cute-grid-list cols="3" rowHeight="100px">`
+ */
+declare class FixedTileStyler extends TileStyler {
+    fixedRowHeight: string;
+    constructor(fixedRowHeight: string);
+    init(gutterSize: string, tracker: TileCoordinator, cols: number, direction: string): void;
+    setRowStyles(tile: CuteGridTile, rowIndex: number): void;
+    getComputedHeight(): [string, string];
+    reset(list: TileStyleTarget): void;
+}
+/**
+ * This type of styler is instantiated when the user passes in a width:height ratio
+ * for the row height.  Example `<cute-grid-list cols="3" rowHeight="3:1">`
+ */
+declare class RatioTileStyler extends TileStyler {
+    /** Ratio width:height given by user to determine row height. */
+    rowHeightRatio: number;
+    baseTileHeight: string;
+    constructor(value: string);
+    setRowStyles(tile: CuteGridTile, rowIndex: number, percentWidth: number, gutterWidth: number): void;
+    getComputedHeight(): [string, string];
+    reset(list: TileStyleTarget): void;
+    private _parseRatio;
+}
+/**
+ * This type of styler is instantiated when the user selects a "fit" row height mode.
+ * In other words, the row height will reflect the total height of the container divided
+ * by the number of rows.  Example `<cute-grid-list cols="3" rowHeight="fit">`
+ */
+declare class FitTileStyler extends TileStyler {
+    setRowStyles(tile: CuteGridTile, rowIndex: number): void;
+    reset(list: TileStyleTarget): void;
+}
+
+/**
+ * @license Apache-2.0
+ *
+ * Copyright (c) 2025 CuteWidgets Team. All Rights Reserved.
+ *
+ * You may not use this file except in compliance with the License
+ * that can be found at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * This code is a modification of the `@angular/material` original
+ * code licensed under MIT-style License (https://angular.dev/license).
+ */
+
+declare class CuteGridList implements CuteGridListBase, OnInit, AfterContentChecked, TileStyleTarget {
+    private _element;
+    private _dir;
+    /** Number of columns being rendered. */
+    private _cols;
+    /** Used for determining the position of each tile in the grid. */
+    private _tileCoordinator;
+    /**
+     * Row height value passed in by user. This can be one of three types:
+     * - Number value (ex: "100px"):  sets a fixed row height to that value
+     * - Ratio value (ex: "4:3"): sets the row height based on width:height ratio
+     * - "Fit" mode (ex: "fit"): sets the row height to total height divided by number of rows
+     */
+    private _rowHeight;
+    /** The amount of space between tiles. This will be something like '5px' or '2em'. */
+    private _gutter;
+    /** Sets position and size styles for a tile */
+    private _tileStyler;
+    /** Query list of tiles that are being rendered. */
+    _tiles: QueryList<CuteGridTile>;
+    constructor(...args: unknown[]);
+    /** Amount of columns in the grid list. */
+    get cols(): number;
+    set cols(value: NumberInput);
+    /** Size of the grid list's gutter in pixels. */
+    get gutterSize(): string;
+    set gutterSize(value: string);
+    /** Set an internal representation of row height from the user-provided value. */
+    get rowHeight(): string | number;
+    set rowHeight(value: string | number);
+    ngOnInit(): void;
+    /**
+     * The layout calculation is fairly cheap if nothing changes, so there's little cost
+     * to run it frequently.
+     */
+    ngAfterContentChecked(): void;
+    /** Throw a friendly error if cols property is missing */
+    private _checkCols;
+    /** Default to equal width:height if rowHeight property is missing */
+    private _checkRowHeight;
+    /** Creates correct Tile Styler subtype based on rowHeight passed in by user */
+    private _setTileStyler;
+    /** Computes and applies the size and position for all children grid tiles. */
+    private _layoutTiles;
+    /** Sets style on the main grid-list element, given the style name and value. */
+    _setListStyle(style: [string, string | null] | null): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridList, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CuteGridList, "cute-grid-list", ["cuteGridList"], { "cols": { "alias": "cols"; "required": false; }; "gutterSize": { "alias": "gutterSize"; "required": false; }; "rowHeight": { "alias": "rowHeight"; "required": false; }; }, {}, ["_tiles"], ["*"], true, never>;
+}
+
+declare class CuteGridListModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CuteGridListModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<CuteGridListModule, never, [typeof i1.CommonModule, typeof i2.CuteLineModule, typeof CuteGridList, typeof CuteGridTile, typeof CuteGridTileText, typeof CuteGridTileHeaderCssCuteStyler, typeof CuteGridTileFooterCssCuteStyler, typeof CuteGridAvatarCssCuteStyler], [typeof i2.CuteLineModule, typeof CuteGridList, typeof CuteGridTile, typeof CuteGridTileText, typeof CuteGridTileHeaderCssCuteStyler, typeof CuteGridTileFooterCssCuteStyler, typeof CuteGridAvatarCssCuteStyler]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<CuteGridListModule>;
+}
+
+export { CuteGridAvatarCssCuteStyler, CuteGridList, CuteGridListModule, CuteGridTile, CuteGridTileFooterCssCuteStyler, CuteGridTileHeaderCssCuteStyler, CuteGridTileText, FitTileStyler, FixedTileStyler, RatioTileStyler, TileStyler };
+export type { TileStyleTarget };