mates-devtools 0.1.0-beta.1

package/dist/types/lib/virtualizer/mates-adapter.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Mates adapter for @lit-labs/virtualizer (forked).
+ *
+ * Exposes `virtualList`, `virtualGrid`, and `virtualMasonry` — the same
+ * friendly API that mates users already know — but now backed by the
+ * battle-tested lit virtualizer engine.
+ *
+ * Key improvement over the old repeatVirtual implementation:
+ *   - `virtualList` no longer requires `itemHeight`. The FlowLayout uses
+ *     ResizeObserver to measure each child's actual rendered height, just
+ *     like the browser's native flow layout. Items can be any height and
+ *     can change height dynamically.
+ *   - `virtualGrid` and `virtualMasonry` still accept explicit sizes since
+ *     the grid/masonry layouts need them for position pre-computation.
+ */
+import type { TemplateResult } from "lit-html";
+import type { KeyFn } from "lit-html/directives/repeat.js";
+export type VirtualItemTemplate<T> = (item: T, index: number) => TemplateResult;
+export type VirtualKeyFn<T> = KeyFn<T>;
+export interface VirtualListOptions {
+    /**
+     * Scrolling direction. Defaults to `'vertical'`.
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * If true the virtualizer element itself becomes the scroller.
+     * Set an explicit height/width on the host element when using this.
+     */
+    scroller?: boolean;
+    /**
+     * Pin a specific item into view on first render.
+     * e.g. `{ index: 100, block: 'start' }`
+     */
+    pin?: {
+        index: number;
+        block?: ScrollLogicalPosition;
+    };
+}
+/**
+ * `virtualList` — virtualised single-column list backed by the lit virtualizer
+ * FlowLayout.
+ *
+ * Unlike the previous implementation, **no `itemHeight` is required**. Each
+ * item is measured by a ResizeObserver after it renders, so items can have
+ * any height — fixed, dynamic, or content-driven — and the virtualizer adapts
+ * automatically.
+ *
+ * The parent element of the expression becomes the scroll container. Give it
+ * a fixed height via CSS or inline style.
+ *
+ * @example
+ * ```ts
+ * // Minimal — items can be any height
+ * html`<div style="height:600px;overflow:auto">
+ *   ${virtualList(items, (item) => html`<div>${item.name}</div>`)}
+ * </div>`
+ *
+ * // With explicit key function
+ * html`<div style="height:600px;overflow:auto">
+ *   ${virtualList(
+ *     items,
+ *     (item) => item.id,
+ *     (item) => html`<div>${item.name}</div>`,
+ *   )}
+ * </div>`
+ *
+ * // Horizontal list
+ * html`<div style="width:800px;overflow:auto">
+ *   ${virtualList(
+ *     items,
+ *     (item) => item.id,
+ *     (item) => html`<div style="width:120px">${item.name}</div>`,
+ *     { direction: 'horizontal' },
+ *   )}
+ * </div>`
+ * ```
+ */
+export declare function virtualList<T>(items: readonly T[], template: VirtualItemTemplate<T>, options?: VirtualListOptions): unknown;
+export declare function virtualList<T>(items: readonly T[], keyFn: VirtualKeyFn<T>, template: VirtualItemTemplate<T>, options?: VirtualListOptions): unknown;
+export interface VirtualGridOptions {
+    /**
+     * Item width in CSS pixel string, e.g. `'200px'`. Required.
+     */
+    itemWidth: `${number}px`;
+    /**
+     * Item height in CSS pixel string, e.g. `'200px'`. Required.
+     */
+    itemHeight: `${number}px`;
+    /**
+     * Gap between cells. Accepts any value supported by the grid layout,
+     * e.g. `'12px'`, `'12px 8px'`. Defaults to `'8px'`.
+     */
+    gap?: `${number}px` | `${number}px ${number}px`;
+    /**
+     * Scrolling direction. Defaults to `'vertical'`.
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * If true the virtualizer element itself becomes the scroller.
+     */
+    scroller?: boolean;
+    /**
+     * Whether to flex items to fill available space. Defaults to `false`.
+     * Set to `true` to let the grid decide how many columns fit.
+     */
+    flex?: boolean;
+    /**
+     * Pin a specific item into view on first render.
+     */
+    pin?: {
+        index: number;
+        block?: ScrollLogicalPosition;
+    };
+}
+/**
+ * `virtualGrid` — virtualised uniform multi-column grid.
+ *
+ * Pass flat items — no row-grouping needed. The grid layout computes row and
+ * column positions automatically. All cells have the same size.
+ *
+ * @example
+ * ```ts
+ * html`<div style="height:600px;overflow:auto">
+ *   ${virtualGrid(
+ *     photos,
+ *     (p) => p.id,
+ *     (p) => html`<img src=${p.url} style="width:100%;height:100%;object-fit:cover" />`,
+ *     { itemWidth: '220px', itemHeight: '220px', gap: '12px' },
+ *   )}
+ * </div>`
+ * ```
+ */
+export declare function virtualGrid<T>(items: readonly T[], template: VirtualItemTemplate<T>, options: VirtualGridOptions): unknown;
+export declare function virtualGrid<T>(items: readonly T[], keyFn: VirtualKeyFn<T>, template: VirtualItemTemplate<T>, options: VirtualGridOptions): unknown;
+export interface VirtualMasonryOptions {
+    /**
+     * A function that returns the aspect ratio (width / height) of each item.
+     * This is used by the masonry layout to compute item heights based on column
+     * width. Required.
+     */
+    getAspectRatio: (item: unknown) => number;
+    /**
+     * Item size (column width) as a CSS pixel string, e.g. `'300px'`.
+     * The masonry layout derives height from the aspect ratio, so only one
+     * dimension is needed. Defaults to `'300px'`.
+     */
+    itemSize?: `${number}px` | "0";
+    /**
+     * Gap between items. Defaults to `'8px'`.
+     */
+    gap?: `${number}px` | `${number}px ${number}px`;
+    /**
+     * Scrolling direction. Defaults to `'vertical'`.
+     */
+    direction?: "vertical" | "horizontal";
+    /**
+     * If true the virtualizer element itself becomes the scroller.
+     */
+    scroller?: boolean;
+    /**
+     * Pin a specific item into view on first render.
+     */
+    pin?: {
+        index: number;
+        block?: ScrollLogicalPosition;
+    };
+}
+/**
+ * `virtualMasonry` — virtualised masonry grid with variable item heights.
+ *
+ * Positions are computed automatically using the lit virtualizer's MasonryLayout,
+ * which places items in the shortest column (greedy algorithm). Provide
+ * `getAspectRatio` to let the layout derive each item's height from its
+ * column width.
+ *
+ * @example
+ * ```ts
+ * html`<div style="height:600px;overflow:auto">
+ *   ${virtualMasonry(
+ *     photos,
+ *     (p) => p.id,
+ *     (p) => html`
+ *       <img src=${p.url}
+ *            style="width:100%;height:100%;object-fit:cover;border-radius:8px" />
+ *     `,
+ *     {
+ *       getAspectRatio: (p) => p.width / p.height,
+ *       itemWidth: '220px',
+ *       gap: '12px',
+ *     },
+ *   )}
+ * </div>`
+ * ```
+ */
+export declare function virtualMasonry<T>(items: readonly T[], template: VirtualItemTemplate<T>, options: VirtualMasonryOptions): unknown;
+export declare function virtualMasonry<T>(items: readonly T[], keyFn: VirtualKeyFn<T>, template: VirtualItemTemplate<T>, options: VirtualMasonryOptions): unknown;
+//# sourceMappingURL=mates-adapter.d.ts.map

package/dist/types/lib/virtualizer/mates-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mates-adapter.d.ts","sourceRoot":"","sources":["../../../../../lib/virtualizer/mates-adapter.ts"],"names":[],"mappings":"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"}

package/dist/types/lib/virtualizer/virtualize.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2021 Google LLC
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+import { type ChildPart, type TemplateResult } from "lit-html";
+import { AsyncDirective } from "lit-html/async-directive.js";
+import { type DirectiveResult, type PartInfo } from "lit-html/directive.js";
+import { type KeyFn } from "lit-html/directives/repeat.js";
+import type { LayoutConfigValue } from "./layouts/shared/Layout.js";
+import { Virtualizer } from "./Virtualizer.js";
+export type { VirtualizerHostElement } from "./Virtualizer.js";
+export { virtualizerRef } from "./Virtualizer.js";
+/**
+ * Configuration options for the virtualize directive.
+ */
+export interface VirtualizeDirectiveConfig<T> {
+    /**
+     * A function that returns a lit-html TemplateResult. It will be used
+     * to generate the DOM for each item in the virtual list.
+     */
+    renderItem?: RenderItemFunction<T>;
+    keyFunction?: KeyFn<T>;
+    scroller?: boolean;
+    layout?: LayoutConfigValue;
+    /**
+     * The list of items to display via the renderItem function.
+     */
+    items?: Array<T>;
+}
+export type RenderItemFunction<T = unknown> = (item: T, index: number) => TemplateResult;
+export declare const defaultKeyFunction: KeyFn<unknown>;
+export declare const defaultRenderItem: RenderItemFunction<unknown>;
+declare class VirtualizeDirective<T = unknown> extends AsyncDirective {
+    _virtualizer: Virtualizer | null;
+    _first: number;
+    _last: number;
+    _renderItem: RenderItemFunction<T>;
+    _keyFunction: KeyFn<T>;
+    _items: Array<T>;
+    constructor(part: PartInfo);
+    render(config?: VirtualizeDirectiveConfig<T>): unknown;
+    update(part: ChildPart, [config]: [VirtualizeDirectiveConfig<T>]): unknown;
+    private _updateVirtualizerConfig;
+    private _setFunctions;
+    private _makeVirtualizer;
+    private _initialize;
+    disconnected(): void;
+    reconnected(): void;
+}
+export declare const virtualize: <T>(config?: VirtualizeDirectiveConfig<T>) => DirectiveResult<typeof VirtualizeDirective>;
+//# sourceMappingURL=virtualize.d.ts.map

package/dist/types/lib/virtualizer/virtualize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"virtualize.d.ts","sourceRoot":"","sources":["../../../../../lib/virtualizer/virtualize.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,SAAS,EAAkB,KAAK,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACL,KAAK,eAAe,EAEpB,KAAK,QAAQ,EAEd,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,KAAK,KAAK,EAAU,MAAM,+BAA+B,CAAC;AAEnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,YAAY,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC;IAC1C;;;OAGG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAEnC,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;IAEvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IAGnB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAE3B;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC;CAClB;AAED,MAAM,MAAM,kBAAkB,CAAC,CAAC,GAAG,OAAO,IAAI,CAC5C,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,MAAM,KACV,cAAc,CAAC;AAEpB,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,OAAO,CAA2B,CAAC;AAC1E,eAAO,MAAM,iBAAiB,EAAE,kBAAkB,CAAC,OAAO,CAGP,CAAC;AAEpD,cAAM,mBAAmB,CAAC,CAAC,GAAG,OAAO,CAAE,SAAQ,cAAc;IAC3D,YAAY,EAAE,WAAW,GAAG,IAAI,CAAQ;IACxC,MAAM,SAAK;IACX,KAAK,SAAM;IACX,WAAW,EAAE,kBAAkB,CAAC,CAAC,CAAC,CACW;IAC7C,YAAY,EAAE,KAAK,CAAC,CAAC,CAAC,CACwB;IAC9C,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAM;gBAEV,IAAI,EAAE,QAAQ;IAS1B,MAAM,CAAC,MAAM,CAAC,EAAE,yBAAyB,CAAC,CAAC,CAAC;IAc5C,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,CAAC;YAYlD,wBAAwB;IActC,OAAO,CAAC,aAAa;IAUrB,OAAO,CAAC,gBAAgB;IAaxB,OAAO,CAAC,WAAW;IAYnB,YAAY;IAIZ,WAAW;CAGZ;AAED,eAAO,MAAM,UAAU,EAAqC,CAAC,CAAC,EAC5D,MAAM,CAAC,EAAE,yBAAyB,CAAC,CAAC,CAAC,KAClC,eAAe,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mates-devtools",
+  "version": "0.1.0-beta.1",
+  "description": "In-app DevTools panel for the Mates framework",
+  "type": "module",
+  "main": "./dist/mates-devtools.umd.js",
+  "module": "./dist/mates-devtools.es.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/mates-devtools.es.js",
+      "require": "./dist/mates-devtools.umd.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "mates",
+    "devtools",
+    "developer-tools",
+    "debugging"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "mates": "*"
+  },
+  "devDependencies": {
+    "happy-dom": "^20.8.4",
+    "mates": "0.1.0-beta.11",
+    "typescript": "^5.3.2",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  }
+}