# @thoschu/canvas-web-component Project This project is a Stencil.js web component that enables HTML content to be rendered into a canvas element or converted into an image. It supports various options for customization, including canvas size, cross-origin image handling, and clipboard integration. This project is built with [Stencil.js](https://stenciljs.com/), a compiler for building fast, reusable Web Components. The project leverages Stencil to create modern, framework-agnostic components that can be used in any web application, including those built with frameworks like Angular, React, or Vue.js. ## Features - Canvas Rendering: Convert HTML elements into a canvas or image. - Clipboard Support: Easily copy the canvas as an image to the clipboard. - Customizable Options: Fine-tune rendering settings, including background color, CORS handling, scaling, and more. - Dynamic API: Methods to retrieve the current canvas or image at runtime. - Shadow DOM Support: Encapsulated styling and rendering. ## Project Overview - **src/**: Contains the main source code for the Stencil components. - **www/**: The output folder for the web deployment build. - **dist/**: Contains the compiled distribution files for reuse in other projects. - **stencil.config.ts**: Configuration file for the Stencil compiler. - **package.json**: Manages the dependencies, scripts, and project metadata. - **tsconfig.json**: TypeScript configuration for the project. ## Prerequisites To work with this project, ensure you have the following installed: - Node.js (v14.x or later) - npm (v6.x or later) ## Installation You can install the component using npm or include it directly via CDN. ### Using npm ```bash npm install canvas-component ``` ### Using unpkg **https://stenciljs.com/docs/publishing** If you prefer not to use npm, you can include the component directly from a CDN like **unpkg**. For example, include the following script in your HTML: ```html ``` For browsers that don't support ES modules, use the following fallback: ```html ``` This allows you to use the components directly in your HTML pages without the need for any installation. ```html Stencil Component Starter >
Avatar

Hello World

Tom S.

Architect & Engineer from Hamburg - Germany
``` ## Usage Once included, you can use the `canvas-component` in your HTML like any other element. ### Basic Example ```html ``` ### Copy to Clipboard Example To enable copying the canvas content to the clipboard on click, use the `copy` property: ```html ``` ### Set Image Type Specify whether the component should render as a canvas or an image using the `type` property: ```html ``` ## Configuration The `config` property allows you to customize how the HTML content is rendered into the canvas. Below are the available options: ### Config Options - **`allowTaint`**: Boolean indicating whether to allow cross-origin images to taint the canvas. - **`backgroundColor`**: The background color of the canvas. Use `null` for a transparent background. - **`canvas`**: An existing canvas element to use for drawing. - **`foreignObjectRendering`**: Enable foreign object rendering, where supported. - **`imageTimeout`**: Timeout for loading images in milliseconds. - **`ignoreElements`**: Function to ignore certain elements during rendering. - **`logging`**: Enable logging for debugging. - **`onclone`**: Callback function for modifying the cloned document before rendering. - **`proxy`**: URL of a proxy to load cross-origin images. - **`removeContainer`**: Whether to remove temporary DOM elements after rendering. - **`scale`**: The scaling factor for rendering. Defaults to the device pixel ratio. - **`useCORS`**: Boolean for attempting to load images with CORS to avoid tainting. - **`width`**: The width of the canvas. - **`height`**: The height of the canvas. - **`x`, `y`**: Coordinates for cropping the canvas. - **`scrollX`, `scrollY`**: Scroll positions for rendering the element. - **`windowWidth`, `windowHeight`**: The window dimensions for rendering. ### Example with Configuration ```html ``` ## API Methods - **`get(type: "canvas" | "image")`**: Returns the current canvas or image element. ### Example Usage ```typescript const canvasComponent = document.querySelector('canvas-component'); // Get the canvas element const canvas = await canvasComponent.get('canvas'); // Get the image element const image = await canvasComponent.get('image'); ``` ## Angular Integration You can use this web component in an **Angular** project by following these steps: ### Step 1: Install the Component First, install the component via npm: ```bash npm install canvas-component ``` ### Step 2: Add Custom Elements Schema Update your `AppModule` to include `CUSTOM_ELEMENTS_SCHEMA` to support custom elements: ```typescript import { NgModule, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { AppComponent } from './app.component'; @NgModule({ declarations: [AppComponent], imports: [BrowserModule], schemas: [CUSTOM_ELEMENTS_SCHEMA], // Add this line bootstrap: [AppComponent] }) export class AppModule { } ``` ### Step 3: Add Scripts to `angular.json` Add the JavaScript files for the web component to the `scripts` section in `angular.json`: ```json { "scripts": [ "node_modules/canvas-component/dist/canvas-component/canvas-component.js" ] } ``` or like this: ```typescript import { APP_INITIALIZER, ApplicationConfig, CUSTOM_ELEMENTS_SCHEMA, provideZoneChangeDetection } from '@angular/core'; import { provideRouter } from '@angular/router'; import { defineCustomElements } from '@thoschu/canvas-web-component/loader'; import { routes } from './app.routes'; export const appConfig: ApplicationConfig = { providers: [provideZoneChangeDetection({ eventCoalescing: true }), provideRouter(routes), { provide: APP_INITIALIZER, useFactory: () => defineCustomElements, multi: true }, ], }; ``` ### Step 4: Use the Component in Angular Now you can use the `canvas-component` in your Angular templates: ```html ``` ### Using with React or Vue.js Stencil components can be easily integrated into React and Vue.js as well. For React, you can wrap the web components in a React component using `createRef`. For Vue.js, the components can be directly used in the templates. ### Browser Support Stencil components are compiled down to vanilla JavaScript, ensuring compatibility with all modern browsers. If older browsers are a concern, make sure to include the necessary polyfills. ## Features Discover the different features supported by this web component ### Below is a list of all the supported CSS properties and values. - background + background-clip (Does not support text) + background-color + background-image * url() * linear-gradient() * radial-gradient() + background-origin + background-position + background-size - border + border-color + border-radius + border-style + border-width - bottom - box-sizing - content - color - display - flex - float - font + font-family + font-size + font-style + font-variant + font-weight - height - left - letter-spacing - line-break - list-style + mlist-style-image + list-style-position + list-style-type - margin - max-height - max-width - min-height - min-width - opacity - overflow - overflow-wrap - padding - paint-order - position - right - text-align - text-decoration + text-decoration-color + text-decoration-line + text-decoration-style (Only supports solid) - text-shadow - text-transform - top - transform (Limited support) - visibility - white-space - width - webkit-text-stroke - word-break - word-spacing - word-wrap - z-index ### Unsupported CSS properties These CSS properties are NOT currently supported - background-blend-mode - border-image - box-decoration-break - box-shadow - filter - font-variant-ligatures - mix-blend-mode - object-fit - repeating-linear-gradient() - writing-mode - zoom ## Development 1. Clone the repository: ```bash git clone git@github.com:thoschu/stencil.js.git cd stencil.js ``` 2. Install the project dependencies: ```bash npm install ``` 3. Start the development server and begin building components: ```bash npm start ``` This will launch a local development server with live-reload functionality. Any changes made to the components in the `src/` folder will automatically trigger a browser reload. 4. To create a production build of the components, run: ```bash npm run build ``` The compiled files will be output to the `www/` and `dist/` directories. These files can be used in a standalone fashion or integrated into other projects. ## Contributing Contributions are welcome! If you have ideas for improvements or find any issues, feel free to open a pull request or file an issue. ## License This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details. ## Additional Resources For more information on using Stencil.js, check out the official [Stencil Documentation](https://stenciljs.com/docs).