Initial commit.

.github/workflows/main.yml

@@ -0,0 +1,20 @@
+name: Tests
+on: [push, pull_request, workflow_dispatch]
+permissions:
+  contents: read
+  packages: read
+jobs:
+  test:
+    name: Testing code.
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/[email protected]
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 21
+      - name: Installing dependencies.
+        run: yarn install
+      - name: Running tests.
+        run: yarn run tests
+      - name: Linting check.
+        run: yarn run lint

.gitignore

@@ -0,0 +1,3 @@
+/.idea/
+/*.iml
+/yarn.lock

LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2024-present Łukasz Zaroda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

eslint.config.mjs

@@ -0,0 +1,24 @@
+import globals from "globals";
+import pluginJs from "@eslint/js";
+import tseslint from "typescript-eslint";
+import eslintPluginPrettierRecommended from 'eslint-plugin-prettier/recommended';
+
+export default [
+    {files: ["**/*.{js,mjs,cjs,ts}"]},
+    {languageOptions: {globals: globals.browser}},
+    pluginJs.configs.recommended,
+    ...tseslint.configs.recommended,
+    eslintPluginPrettierRecommended,
+    {
+      languageOptions: {
+        parserOptions: {
+          project: "./tsconfig.json",
+        }
+      },
+      rules: {
+          "@typescript-eslint/no-explicit-any": "off",
+          "@typescript-eslint/no-empty-object-type": "off",
+          "@typescript-eslint/prefer-as-const": "off",
+      },
+    },
+];

jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} **/
+module.exports = {
+  testEnvironment: "node",
+  transform: {
+    "^.+.tsx?$": ["ts-jest",{}],
+  },
+  preset: "ts-jest",
+};

package.json

@@ -0,0 +1,41 @@
+{
+  "name": "wraplet",
+  "version": "0.5.0",
+  "description": "",
+  "main": "dist/index.js",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lukasz-zaroda/wraplet.git"
+  },
+  "scripts": {
+    "setup": "yarn install",
+    "build": "./node_modules/.bin/webpack --mode production --config ./webpack.config.js",
+    "dev:build": "./node_modules/.bin/webpack --mode development --config ./webpack.config.js",
+    "dev:watch": "./node_modules/.bin/webpack --mode development --watch --config ./webpack.config.js",
+    "lint": "tsc --noemit && npx eslint './src/**/*.ts' './tests/**/*.ts'",
+    "lint:fix": "npx eslint './src/**/*.ts' './tests/**/*.ts' --fix",
+    "tests": "jest"
+  },
+  "dependencies": {
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "ts-loader": "^9.5.1",
+    "@eslint/js": "^9.9.1",
+    "eslint": "^9.9.1",
+    "globals": "^15.9.0",
+    "typescript-eslint": "^8.2.0",
+    "webpack": "^5.94.0",
+    "webpack-cli": "^5.1.4",
+    "prettier": "^3.3.3",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "prettier-eslint": "^16.3.0",
+    "jest": "^29.7.0",
+    "jest-cli": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "@types/jest": "^29.5.12",
+    "jest-environment-jsdom": "^29.7.0"
+  }
+}

src/AbstractWraplet.ts

@@ -0,0 +1,165 @@
+import { WrapletChildrenMap } from "./types/WrapletChildrenMap";
+import { WrapletChildren } from "./types/WrapletChildren";
+import { Wraplet } from "./types/Wraplet";
+import { DeepWriteable, Nullable } from "./types/Utils";
+import { MapError, MissingRequiredChildError } from "./errors";
+
+export abstract class AbstractWraplet<
+  T extends WrapletChildrenMap = {},
+  E extends Element = Element,
+> implements Wraplet
+{
+  public isWraplet: true = true;
+
+  protected children: WrapletChildren<T>;
+  protected static debug: boolean = false;
+
+  constructor(
+    protected element: E,
+    mapAlterCallback: ((map: DeepWriteable<T>) => void) | null = null,
+  ) {
+    const map = this.buildChildrenMap();
+    if (mapAlterCallback) {
+      mapAlterCallback(map);
+    }
+    this.children = this.instantiateChildren(map);
+    if (!this.element.wraplets) {
+      this.element.wraplets = [];
+    }
+    this.element.wraplets.push(this);
+  }
+
+  protected abstract buildChildrenMap(): T;
+
+  protected instantiateChildren(map: T): WrapletChildren<T> {
+    const children: Partial<Nullable<WrapletChildren<T>>> = {};
+    for (const id in map) {
+      const item = map[id];
+      const selector = item.selector;
+      const wrapletClass = item.Class;
+      const args = item.args || [];
+      const multiple = item.multiple;
+      const isRequired = item.required;
+
+      if (!selector) {
+        if (isRequired) {
+          throw new MapError(
+            `${this.constructor.name}: Child "${id}" cannot at the same be required and have no selector.`,
+          );
+        }
+
+        children[id] = multiple
+          ? ([] as WrapletChildren<T>[keyof WrapletChildren<T>])
+          : null;
+        continue;
+      }
+
+      const childElements = this.element.querySelectorAll(selector);
+      if (childElements.length === 0) {
+        if (isRequired) {
+          throw new MissingRequiredChildError(
+            `${this.constructor.name}: Couldn't find an element for the wraplet "${id}". Selector used: "${selector}".`,
+          );
+        }
+        if ((this.constructor as any).debug) {
+          console.log(
+            `${this.constructor.name}: Optional child '${id}' has not been found. Selector used: "${selector}"`,
+          );
+        }
+        children[id] = multiple
+          ? ([] as WrapletChildren<T>[keyof WrapletChildren<T>])
+          : null;
+
+        continue;
+      }
+
+      const childWraplet: Wraplet[] = [];
+      for (const childElement of childElements) {
+        childWraplet.push(this.createWraplet(wrapletClass, childElement, args));
+        if (!multiple) {
+          break;
+        }
+      }
+
+      const value: Wraplet | Wraplet[] = multiple
+        ? childWraplet
+        : childWraplet[0];
+      if (multiple && !value && (this.constructor as any).debug) {
+        console.log(
+          `${this.constructor.name}: no items for the multiple child '${id}' have been found. Selector used: "${selector}"`,
+        );
+      }
+      if (!this.childTypeGuard(value, id)) {
+        if (typeof value === "undefined") {
+          throw new Error(
+            `${this.constructor.name}: Couldn't intantionate the "${id}" child. Selector used: "${selector}".`,
+          );
+        }
+        throw new Error(
+          `${this.constructor.name}: Child value doesn't match the map. Value: ${value}. Expected: ${map[id]["Class"].name}`,
+        );
+      }
+
+      children[id] = value;
+    }
+
+    // Now we should have all properties set, so let's assert the final form.
+    return children as WrapletChildren<T>;
+  }
+
+  protected createWraplet(
+    wrapletClass: new (...args: any[]) => Wraplet,
+    childElement: Element,
+    args: unknown[] = [],
+  ): Wraplet {
+    return new wrapletClass(...[...[childElement], ...args]);
+  }
+
+  private childTypeGuard<S extends keyof WrapletChildren<T>>(
+    variable: Wraplet | Wraplet[] | null,
+    id: S,
+  ): variable is WrapletChildren<T>[S] {
+    const map = this.buildChildrenMap();
+    const Class = map[id].Class;
+    const isRequired = map[id].required;
+    const isMultiple = map[id].multiple;
+    if (isMultiple) {
+      const isArray = Array.isArray(variable);
+      if (!isArray) {
+        return false;
+      }
+      if (isRequired) {
+        return variable.every((value) => value instanceof Class);
+      }
+
+      return true;
+    }
+
+    if (isRequired) {
+      return variable instanceof Class;
+    }
+
+    return variable instanceof Class || variable === null;
+  }
+
+  // We can afford "any" here because this method is only for the external usage, and external
+  // callers don't need to know what map is the current wraplet using, as it's its internal
+  // matter.
+  protected static createWraplets<T extends AbstractWraplet<any> = never>(
+    document: Document,
+    additional_args: unknown[] = [],
+    selector: string,
+  ): T[] {
+    if (this instanceof AbstractWraplet) {
+      throw new Error("You cannot instantiate an abstract class.");
+    }
+
+    const result: T[] = [];
+    const foundElements = document.querySelectorAll(selector);
+    for (const element of foundElements) {
+      result.push(new (this as any)(element, ...additional_args));
+    }
+
+    return result;
+  }
+}

src/errors.ts

@@ -0,0 +1,3 @@
+export class MissingRequiredChildError extends Error {}
+
+export class MapError extends Error {}

src/index.ts

@@ -0,0 +1,4 @@
+export { AbstractWraplet } from "./AbstractWraplet";
+export { WrapletChildrenMap } from "./types/WrapletChildrenMap";
+
+import "./types/global";

src/types/Utils.ts

@@ -0,0 +1,11 @@
+export type InstantiableReturnType<T> = T extends {
+  new (...args: any[]): infer R;
+}
+  ? R
+  : never;
+
+export type Nullable<T> = { [K in keyof T]: T[K] | null };
+
+export type DeepWriteable<T> = {
+  -readonly [P in keyof T]: DeepWriteable<T[P]>;
+};

src/types/Wraplet.ts

@@ -0,0 +1,3 @@
+export interface Wraplet {
+  isWraplet: true;
+}

src/types/WrapletChildDefinition.ts

@@ -0,0 +1,11 @@
+import { AbstractWraplet } from "../AbstractWraplet";
+
+export type WrapletChildDefinition<
+  T extends AbstractWraplet = AbstractWraplet,
+> = {
+  selector?: string;
+  Class: { new (...args: any[]): T };
+  required: boolean;
+  multiple: boolean;
+  args?: unknown[];
+};

src/types/WrapletChildren.ts

@@ -0,0 +1,10 @@
+import { WrapletChildrenMap } from "./WrapletChildrenMap";
+import { InstantiableReturnType } from "./Utils";
+
+export type WrapletChildren<T extends WrapletChildrenMap> = {
+  [id in keyof T]: T[id]["multiple"] extends true
+    ? InstantiableReturnType<T[id]["Class"]>[]
+    : T[id]["required"] extends true
+      ? InstantiableReturnType<T[id]["Class"]>
+      : InstantiableReturnType<T[id]["Class"]> | null;
+};

src/types/WrapletChildrenMap.ts

@@ -0,0 +1,5 @@
+import { WrapletChildDefinition } from "./WrapletChildDefinition";
+
+export type WrapletChildrenMap = {
+  [id: string]: WrapletChildDefinition;
+};

src/types/global.ts

@@ -0,0 +1,7 @@
+import { Wraplet } from "./Wraplet";
+
+declare global {
+  interface Element {
+    wraplets?: Wraplet[];
+  }
+}

tests/map.test.ts

@@ -0,0 +1,39 @@
+/**
+ * @jest-environment jsdom
+ */
+import "./setup";
+import { AbstractWraplet, WrapletChildrenMap } from "../src";
+import { BaseTestWraplet } from "./resources/BaseTestWraplet";
+import { MapError } from "../src/errors";
+
+const testWrapletSelectorAttribute = "data-test-selector";
+
+class TestWrapletChild extends AbstractWraplet<any> {
+  protected buildChildrenMap(): {} {
+    return {};
+  }
+}
+
+const childrenMap = {
+  children: {
+    Class: TestWrapletChild,
+    multiple: false,
+    required: true,
+  },
+} as const satisfies WrapletChildrenMap;
+
+class TestWraplet extends BaseTestWraplet<typeof childrenMap> {
+  protected buildChildrenMap(): typeof childrenMap {
+    return childrenMap;
+  }
+}
+
+// TESTS START HERE
+
+test("Test that `required` and missing selector are mutually exclusive", () => {
+  document.body.innerHTML = `<div ${testWrapletSelectorAttribute}></div>`;
+  const createWraplet = () => {
+    TestWraplet.create<TestWraplet>(testWrapletSelectorAttribute);
+  };
+  expect(createWraplet).toThrowError(MapError);
+});