@skeletonizer/vue 0.0.18-alpha.0 → 0.0.20-alpha.0

package/README.md

@@ -1,46 +1,275 @@
-# skeletonizer
+# @skeletonizer/vue
+This is the Vue adapter for Skeletonizer. It provides a simple way to create skeletonized views for your Vue application.
 
-This template should help get you started developing with Vue 3 in Vite.
+## Installation
+To install the package, run the following command:
+`npm install @skeletonizer/vue @skeletonizer/utils --save`
 
-## Recommended IDE Setup
+`@skeletonizer/vue` is always used in conjunction with `@skeletonizer/utils`. The `@skeletonizer/utils` package provides the core functionality for creating skeletonized views, while the `@skeletonizer/vue` package provides the Vue-specific functionality. **The versions should always match**.
 
-[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
+## main.ts
+In your `main.ts` file (where you do `createApp`), you need to install the `SkeletonizerPlugin`. The plugin provides the `SkeletonizerSkeleton` component and directive that will be used in your Vue components.
 
-## Type Support for `.vue` Imports in TS
+```typescript
+import { createApp } from 'vue';
+import App from './App.vue';
+import { SkeletonizerPlugin } from '@skeletonizer/vue';
 
-TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin) to make the TypeScript language service aware of `.vue` types.
+createApp(App)
+  .use(SkeletonizerPlugin)
+  .mount('#app')
+```
 
-If the standalone TypeScript plugin doesn't feel fast enough to you, Volar has also implemented a [Take Over Mode](https://github.com/johnsoncodehk/volar/discussions/471#discussioncomment-1361669) that is more performant. You can enable it by the following steps:
+## Component Adjustments
+Generally speaking, all you need to do to use the skeletonizer in the template, is to wrap the part of the template you wish to skeletonize in the `<skeletonizer-skeleton>` component. The `skeletonizer.skeletonConfig`, `skeletonizer.showSkeleton` and `scope` properties must be passed to the `<skeletonizer-skeleton>` as inputs.
+Furthermore, all the data that you wish to access in the skeletonized part of the template must be accessed through the `skeletonizer.proxy(context)` method, except the data that you provide and is available even whilst the data is being loaded (ie. `:show-skeleton="true"`)..
 
-1. Disable the built-in TypeScript Extension
-    1) Run `Extensions: Show Built-in Extensions` from VSCode's command palette
-    2) Find `TypeScript and JavaScript Language Features`, right click and select `Disable (Workspace)`
-2. Reload the VSCode window by running `Developer: Reload Window` from the command palette.
+As far as the template goes, it essentially means transforming the code from this:
+```html
+<div>{{ somePropOrMethodCallAvailableAsync }}</div>
+<div>{{ someAlreadyHardCodedOrInputBoundPropAvailableSync }} </div>
+```
 
-## Customize configuration
+into this:
 
-See [Vite Configuration Reference](https://vitejs.dev/config/).
+```html
+<skeletonizer-skeleton [showSkeleton]="showSkeleton" [config]="skeletonConfig" [scope]="{ somePropOrMethodCallAvailableAsync } ">
+    <div>{{ proxy(context).somePropOrMethodCallAvailableAsync }}</div>
+    <div>{{ someAlreadyHardCodedOrInputBoundPropAvailableSync }} </div>
+</skeletonizer-skeleton>
+```
 
-## Project Setup
+As long as the shape of the properties you access within the skeleton part of the template matches the shape of the data you provide in the `scope` and `skeletonConfig` properties, the skeletonized view will be in sync with the actual view, regardless of changes to the design.
 
-```sh
-npm install
-```
+## Usage
+You can use Skeletonizer either in a standalone component or in a component that is a part of a module.
 
-### Compile and Hot-Reload for Development
+If you wish to use Skeletonizer in a standalone component, you need to add `SkeletonizerSkeletonComponent` in the imports of the component.
+The usage in a component that is a part of a module is the same as the standalone component, but you need to add `SkeletonizerSkeletonComponent` in the imports of the **module** where the component is declared.
 
-```sh
-npm run dev
-```
+Every component that uses Skeletonizer should extend `SkeletonAbstractComponent`, which is available in `@skeletonizer/utils`.
+The `SkeletonAbstractComponent` requires you to pass a type argument that represents the data model of the **part(s) of the component that you intend to skeletonize**.
+It also requires you to implement the `skeletonConfig` (type validated against the type argument you pass to `SkeletonAbstractComponent`) and `showSkeleton` properties which must be passed to the `SkeletonizerSkeletonComponent` as inputs.
+By extending the `SkeletonAbstractComponent`, you also get access to the `proxy` method via which you can (type) safely access props and methods **within the skeletonized part of the current component**.
+
+In the skeletonized part of the template, you **must** access the data through the `proxy(context)` method.
+You can think of `proxy(context)` in the same way as you would think of `this` in a class method (or in the template, where the `this` is usually omitted when accessing props / methods and we usually call `foo` instead of `this.foo`). The only difference is that when using `proxy(context)`, the content-projected template will use the mocked values when the `showSkeleton` is `true`, and resolved values when `showSkeleton` is `false` - all while maintaining the type safety.
+
+For more details about the `SkeletonAbstractComponent`, see the [SkeletonAbstractComponent](/packages/utils/README.md#skeletonabstractcomponent) section.
+
+For more details about the `SchemaItem` property, see the [SchemaItem](/packages/utils/README.md#schemaitem) section.
+
+For more details about the `skeletonConfig` property, see the [TSchemaConfig](/packages/utils/README.md#tschemaconfig) section.
+
+
+```typescript
+import { Component } from '@angular/core';
+import { SkeletonizerSkeletonComponent } from '@skeletonizer/angular';
+import { SchemaItem, SkeletonAbstractComponent, TSchemaConfig } from '@skeletonizer/utils';
+import { DomSanitizer } from '@angular/platform-browser';
+
+interface IResource {
+  title: string;
+  link: string;
+  svg: string;
+}
+
+// the svgs are just for the sake of the example
+const learnNgSvg: string = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M5 13.18v4L12 21l7-3.82v-4L12 17l-7-3.82zM12 3L1 9l11 6 9-4.91V17h2V9L12 3z"/></svg>';
+
+const cliDocsSvg: string = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M9.4 16.6L4.8 12l4.6-4.6L8 6l-6 6 6 6 1.4-1.4zm5.2 0l4.6-4.6-4.6-4.6L16 6l6 6-6 6-1.4-1.4z"/></svg>';
+
+const loadingSvg: string = '<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><style>.spinner{transform-origin:center;animation:spinner .75s linear infinite}@keyframes spinner{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}</style><g class="spinner"><circle cx="12" cy="2.5" r="1.5" opacity=".14"/><circle cx="16.75" cy="3.77" r="1.5" opacity=".29"/><circle cx="20.23" cy="7.25" r="1.5" opacity=".43"/><circle cx="21.50" cy="12.00" r="1.5" opacity=".57"/><circle cx="20.23" cy="16.75" r="1.5" opacity=".71"/><circle cx="16.75" cy="20.23" r="1.5" opacity=".86"/><circle cx="12" cy="21.5" r="1.5"/></g></svg>';
+
+type TSkeletonizedPart = Pick<AppComponent, 'resources' | 'otherPropWeWantToUseInSkeletonizedPart'>;
+
+@Component({
+  selector: 'my-component',
+  template: `
+    <h2>{{ pageTitle }}</h2>
+
+    <skeletonizer-skeleton [showSkeleton]="showSkeleton" [config]="skeletonConfig" [scope]="{ resources, otherPropWeWantToUseInSkeletonizedPart }">
+      <ng-template let-context>
+        <span>{{ proxy(context).otherPropWeWantToUseInSkeletonizedPart }}</span>
+
+        <a *ngFor="let resource of proxy(context).resources" target="_blank" rel="noopener" [href]="resource.link">
+          <div [innerHTML]="sanitizer.bypassSecurityTrustHtml(resource.svg)"></div>
+          <span>{{ resource.title }}</span>
+        </a>
+      </ng-template>
+    </skeletonizer-skeleton>
+  `,
+  styleUrls: ['./my-component.component.scss'],
+  // for standalone components, otherwise add SkeletonizerSkeletonComponent to the module imports of the module where MyComponent is declared
+  // standalone: true,
+  // imports: [SkeletonizerSkeletonComponent, NgFor], // ngFor is just for the sake of the example where the *ngFor is used in the template
+})
+export class MyComponent extends SkeletonAbstractComponent<TSkeletonizedPart> implements OnInit {
+  public pageTitle: string = 'Some prop that we do not wish to skeletonize, but wish to use in the view nonetheless';
+  public otherPropWeWantToUseInSkeletonizedPart: string = 'angular';
+
+  public resources: IResource[] = [];
+  public showSkeleton: boolean = true;
 
-### Type-Check, Compile and Minify for Production
+  public readonly skeletonConfig: TSchemaConfig<TSkeletonizedPart> = {
+    repeat: 1,
+    schemaGenerator: () => ({
+      otherPropWeWantToUseInSkeletonizedPart: new SchemaItem<string>().words(3),
+      // Array.from({ length: 5 }, () => ({ ... })) is just a simple way of creating an array of 5 objects - you could also hardcode the array if you wanted to
+      resources: Array.from({ length: 5 }, () => ({
+        title: new SchemaItem<string>().words(3),
+        link: new SchemaItem().identical('https://www.google.com'),
+        svg: new SchemaItem().identical(loadingSvg),
+      })),
+    }),
+  };
 
-```sh
-npm run build
+  public constructor(
+    public readonly sanitizer: DomSanitizer,
+  ) {
+    super();
+  }
+
+  public ngOnInit(): void {
+    // simulate loading data
+    setTimeout(() => {
+      this.resources = [
+        {
+          title: 'Mocked Resolved Resource #1',
+          link: 'https://github.com/lukaVarga/skeletonizer/tree/main/packages/angular/projects/skeletonizer',
+          svg: learnNgSvg,
+        },
+        {
+          title: 'Mocked Resolved Resource #2',
+          link: 'https://github.com/lukaVarga/skeletonizer/tree/main',
+          svg: cliDocsSvg,
+        },
+      ];
+
+      this.otherPropWeWantToUseInSkeletonizedPart = 'loaded title'
+
+      this.showSkeleton = false;
+    }, Math.max(3_000, Math.random() * 10_000));
+  }
+}
 ```
 
-### Run Unit Tests with [Vitest](https://vitest.dev/)
+You can also skeletonize multiple independent parts (ie. parts for which the data gets loaded independently of each-other) of the same component by using the `<skeletonizer-skeleton>` multiple times in the template. Each `skeletonizer-skeleton` component should, in this case, receive its own `showSkeleton` input property, while the `config` and the `scope` can be shared for all of them. That way, the config is defined in a single place and all skeletonized parts enjoy the same level of type safety via the known `proxy(context)` method.
+You can also provide separate config and scope for each `skeletonizer-skeleton` component if needed, although it is recommended that you do not extend `SkeletonAbstractComponent` in this case, and you will need to provide your own (separate) `proxy`-like methods for each of the skeletonized parts of the component to maintain the same level of type safety in the template.
+
+```typescript
+import { Component } from '@angular/core';
+import { SkeletonizerSkeletonComponent } from '@skeletonizer/angular';
+import { SchemaItem, SkeletonAbstractComponent, TSchemaConfig } from '@skeletonizer/utils';
+import { DomSanitizer } from '@angular/platform-browser';
+
+interface IResource {
+  title: string;
+  link: string;
+  svg: string;
+}
+
+// the svgs are just for the sake of the example
+const learnNgSvg: string = '<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path d="M5 13.18v4L12 21l7-3.82v-4L12 17l-7-3.82zM12 3L1 9l11 6 9-4.91V17h2V9L12 3z"/></svg>';
+
+const loadingSvg: string = '<svg width="24" height="24" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><style>.spinner{transform-origin:center;animation:spinner .75s linear infinite}@keyframes spinner{from{transform:rotate(0deg)}to{transform:rotate(360deg)}}</style><g class="spinner"><circle cx="12" cy="2.5" r="1.5" opacity=".14"/><circle cx="16.75" cy="3.77" r="1.5" opacity=".29"/><circle cx="20.23" cy="7.25" r="1.5" opacity=".43"/><circle cx="21.50" cy="12.00" r="1.5" opacity=".57"/><circle cx="20.23" cy="16.75" r="1.5" opacity=".71"/><circle cx="16.75" cy="20.23" r="1.5" opacity=".86"/><circle cx="12" cy="21.5" r="1.5"/></g></svg>';
+
+type TSkeletonizedPart = Pick<AppComponent, 'resources' | 'otherPropWeWantToUseInSkeletonizedPart'>;
+
+@Component({
+  selector: 'my-component',
+  template: `
+    <h2>{{ pageTitle }}</h2>
+
+    <skeletonizer-skeleton [showSkeleton]="showSkeleton" [config]="skeletonConfig" [scope]="{ resources, otherPropWeWantToUseInSkeletonizedPart }">
+      <ng-template let-context>
+        <div class="card-container">
+          <a *ngFor="let resource of proxy(context).resources" class="card" target="_blank" rel="noopener" [href]="resource.link">
+            <div [innerHTML]="sanitizer.bypassSecurityTrustHtml(resource.svg)"></div>
+            <span>{{ resource.title }}</span>
+          </a>
+        </div>
+      </ng-template>
+    </skeletonizer-skeleton>
 
-```sh
-npm run test:unit
+    <skeletonizer-skeleton [showSkeleton]="showOtherSkeleton" [config]="skeletonConfig" [scope]="{ resources, otherPropWeWantToUseInSkeletonizedPart }">
+      <ng-template let-context>
+        <span>{{ proxy(context).otherPropWeWantToUseInSkeletonizedPart }}</span>
+      </ng-template>
+    </skeletonizer-skeleton>
+  `,
+  styleUrls: ['./my-component.component.scss'],
+  // for standalone components, otherwise add SkeletonizerSkeletonComponent to the module imports of the module where MyComponent is declared
+  // standalone: true,
+  // imports: [SkeletonizerSkeletonComponent, NgFor], // ngFor is just for the sake of the example where the *ngFor is used in the template
+})
+export class MyComponent extends SkeletonAbstractComponent<TSkeletonizedPart> implements OnInit {
+  public pageTitle: string = 'Some prop that we do not wish to skeletonize, but wish to use in the view nonetheless';
+  public otherPropWeWantToUseInSkeletonizedPart: string = 'angular';
+
+  public resources: IResource[] = [];
+  public showSkeleton: boolean = true;
+
+  public readonly skeletonConfig: TSchemaConfig<TSkeletonizedPart> = {
+    repeat: 1,
+    schemaGenerator: () => ({
+      otherPropWeWantToUseInSkeletonizedPart: new SchemaItem<string>().words(3),
+      // Array.from({ length: 5 }, () => ({ ... })) is just a simple way of creating an array of 5 objects - you could also hardcode the array if you wanted to
+      resources: Array.from({ length: 5 }, () => ({
+        title: new SchemaItem<string>().words(3),
+        link: new SchemaItem().identical('https://www.google.com'),
+        svg: new SchemaItem().identical(loadingSvg),
+      })),
+    }),
+  };
+
+  public constructor(
+    public readonly sanitizer: DomSanitizer,
+  ) {
+    super();
+  }
+
+  public ngOnInit(): void {
+    setTimeout(() => {
+      this.resources = [
+        {
+          title: 'Mocked Resolved Resource #1',
+          link: 'https://github.com/lukaVarga/skeletonizer/tree/main/packages/angular/projects/skeletonizer',
+          svg: learnNgSvg,
+        },
+        {
+          title: 'Mocked Resolved Resource #2',
+          link: 'https://github.com/lukaVarga/skeletonizer/tree/main',
+          svg: cliDocsSvg,
+        },
+      ];
+
+      this.showSkeleton = false;
+    }, Math.max(3_000, Math.random() * 10_000));
+
+    setTimeout(() => {
+      this.showOtherSkeleton = false;
+    }, Math.max(6_000, Math.random() * 10_000));
+  }
+}
 ```
+
+### Color Scheme
+Generally speaking, you shouldn't need to adjust the color scheme of the skeletonized component in most cases. However, should you need to, the color scheme of the skeletonized views can be customized by providing the `colorScheme` property to the `SkeletonizerSkeletonComponent`.
+
+For more details about the `colorScheme` property, see the [colorScheme](/packages/utils/README.md#colorscheme) section.
+
+## Contributing
+For Angular adapter-specific contributions, run the following commands to get started:
+- `npm install`
+- adjust the code in the `packages/angular` directory
+- run `npm run build` in the `packages/angular` directory
+- adjust the code in the `packages/angular/src/app` directory to make sure the changes can easily be seen in the example app
+- `npm run dev` in the `packages/angular` directory to start the example app
+- update readme file in the `packages/angular` directory
+
+Before submitting a pull request, make sure to run the following commands in `packages/angular` directory:
+- `npm run lint`
+- `npm run type-check`
+- `npm run coverage`
+- `npm run build`

package/dist/components/SkeletonizerSkeleton.vue.d.ts

@@ -1,14 +1,11 @@
-import { UnwrapRef } from 'vue';
 import { ISkeletonizerColorSchema, TSchemaConfig } from '@skeletonizer/utils';
-
+import { UnwrapRef } from 'vue';
 declare const _default: <TSkeletonScopeObject extends object>(__VLS_props: {
     config: TSchemaConfig<TSkeletonScopeObject>;
     showSkeleton: boolean;
     scope: TSkeletonScopeObject;
     colorSchema?: ISkeletonizerColorSchema | undefined;
 } & import('vue').VNodeProps & import('vue').AllowedComponentProps & import('vue').ComponentCustomProps, __VLS_ctx?: {
-    attrs: any;
-    emit: any;
     slots: Readonly<{
         default?: ((props: {
             scope: TSkeletonScopeObject | UnwrapRef<TSkeletonScopeObject>;
@@ -22,6 +19,8 @@ declare const _default: <TSkeletonScopeObject extends object>(__VLS_props: {
             scope: TSkeletonScopeObject | UnwrapRef<TSkeletonScopeObject>;
         }) | undefined;
     };
+    attrs: any;
+    emit: {};
 } | undefined, __VLS_expose?: ((exposed: import('vue').ShallowUnwrapRef<{}>) => void) | undefined, __VLS_setup?: Promise<{
     props: {
         config: TSchemaConfig<TSkeletonScopeObject>;
@@ -44,7 +43,7 @@ declare const _default: <TSkeletonScopeObject extends object>(__VLS_props: {
             scope: TSkeletonScopeObject | UnwrapRef<TSkeletonScopeObject>;
         }) | undefined;
     };
-    emit: any;
+    emit: {};
 }>) => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
     [key: string]: any;
 }> & {
@@ -70,7 +69,10 @@ declare const _default: <TSkeletonScopeObject extends object>(__VLS_props: {
                 scope: TSkeletonScopeObject | UnwrapRef<TSkeletonScopeObject>;
             }) | undefined;
         };
-        emit: any;
+        emit: {};
     } | undefined;
 };
 export default _default;
+type __VLS_PrettifyLocal<T> = {
+    [K in keyof T]: T[K];
+} & {};

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import { default as SkeletonizerPlugin } from './main';
-import { SkeletonizerComponentComposable } from './composables/skeletonizer.component.composable';
 import { default as SkeletonizerSkeleton } from './components/SkeletonizerSkeleton.vue';
-
+import { SkeletonizerComponentComposable } from './composables/skeletonizer.component.composable';
+import { default as SkeletonizerPlugin } from './main';
 export { SkeletonizerSkeleton, SkeletonizerComponentComposable, SkeletonizerPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skeletonizer/vue",
-  "version": "0.0.18-alpha.0",
+  "version": "0.0.20-alpha.0",
   "description": "The way to skeletonize your Vue.js components",
   "author": "Luka Varga",
   "license": "MIT",
@@ -50,33 +50,33 @@
     "lint-staged": "lint-staged"
   },
   "peerDependencies": {
-    "@skeletonizer/utils": "0.0.16-alpha.0",
+    "@skeletonizer/utils": "0.0.20-alpha.0",
     "vue": "^3.3.4"
   },
   "devDependencies": {
     "@tsconfig/node18": "^2.0.1",
     "@types/jsdom": "^21.1.6",
     "@types/node": "^20.12.3",
-    "@vitejs/plugin-vue": "^5.0.4",
-    "@vitest/browser": "1.5.1",
-    "@vue/test-utils": "^2.4.5",
+    "@vitejs/plugin-vue": "^5.1.4",
+    "@vitest/browser": "2.1.2",
+    "@vue/test-utils": "^2.4.6",
     "@vue/tsconfig": "^0.5.1",
     "eslint-plugin-vue": "^9.24.0",
     "jsdom": "^24.0.0",
     "npm-run-all": "^4.1.5",
     "sass": "^1.72.0",
     "typescript": "^5.4.3",
-    "vite": "^5.2.10",
-    "vite-plugin-dts": "^3.9.0",
-    "vitest": "1.5.1",
-    "vue": "^3.4.25",
+    "vite": "^5.4.8",
+    "vite-plugin-dts": "^4.2.3",
+    "vitest": "2.1.2",
+    "vue": "^3.5.11",
     "vue-eslint-parser": "^9.4.2",
-    "vue-tsc": "^1.8.27",
-    "webdriverio": "^8.35.1"
+    "vue-tsc": "^2.1.6",
+    "webdriverio": "^9.1.2"
   },
   "lint-staged": {
     "**/*.{scss,css}": "stylelint --fix",
     "**/*.{ts,js,.vue}": "eslint --fix"
   },
-  "gitHead": "df7b44bcab02f415fbae5d3676de5df2b5011d05"
+  "gitHead": "8c8651dfea6a80f5b85e17ff097e6e23024cc7ac"
 }

package/dist/composables/skeletonizer.component.composable.d.ts

@@ -1,9 +0,0 @@
-import { UnwrapNestedRefs } from 'vue';
-import { SkeletonAbstractComponent, TSchemaConfig } from '@skeletonizer/utils';
-
-export declare class SkeletonizerComponentComposable<T extends object> extends SkeletonAbstractComponent<T> {
-    skeletonConfig: TSchemaConfig<T>;
-    showSkeleton: boolean;
-    private constructor();
-    static generate<T extends object>(skeletonConfig: TSchemaConfig<T>, showSkeleton: boolean): UnwrapNestedRefs<SkeletonizerComponentComposable<T>>;
-}

package/dist/main.d.ts

@@ -1,6 +0,0 @@
-import { App } from 'vue';
-
-declare const _default: {
-    install: (app: App) => void;
-};
-export default _default;