cal.pub0.org/packages/embeds/embed-core/README.md

# embed-core

This is the vanilla JS core script that embeds Cal Link.

## How to use embed on any webpage no matter what framework
See <https://docs.cal.com/integrations/embed>

You can also see various example usages [here](https://github.com/calcom/cal.com/blob/main/packages/embeds/embed-core/index.html)

## Development

Run the following command and then you can test the embed in the automatically opened page `http://localhost:3002`

```bash
yarn dev
```

## Running Tests

Ensure that App is running on port 3000 already and then run following command:

```bash
yarn test-playwright
```

## Shipping to Production

```bash
yarn build
```

Make `dist/embed.umd.js` servable on URL <http://cal.com/embed.js>

## DX

- Hot reload doesn't work with CSS files in the way we use vite.

## Known Bugs and Upcoming Improvements

- Unsupported Browsers and versions. Documenting them and gracefully handling that.

- Accessibility and UI/UX Issues
  - let user choose the loader for ModalBox
  - If website owner links the booking page directly for an event, should the user be able to go to events-listing page using back button ?
  - Let user specify both dark and light theme colors. Right now the colors specified are for light theme.
  - Embed doesn't adapt to screen size without page refresh.
    - Try opening in portrait mode and then go to landscape mode.
  - In inline mode, due to changing height of iframe, the content goes beyond the fold. Automatic scroll needs to be implemented.
  - On Availability page, when selecting date, width doesn't increase. max-width is there but because of strict width restriction with iframe, it doesn't allow it to expand.

- Branding
  - Powered by Cal.com and 'Try it for free'. Should they be shown only for FREE account.
  - Branding at the bottom has been removed for UI improvements, need to see where to add it.

- API
  - Allow loader color customization using UI command itself too.

- Automation Tests
  - Run automation tests in CI

- Bundling Related
  - Comments in CSS aren't stripped off

- Debuggability
  - Send log messages from iframe to parent so that all logs can exist in a single queue forming a timeline.
    - user should be able to use "on" instruction to understand what's going on in the system
  - Error Tracking for embed.js
    - Know where exactly it’s failing if it does.

- Color Scheme
  - Need to reduce the number of colors on booking page, so that UI configuration is simpler

- Dev Experience/Ease of Installation
  - Improved Demo
    - Seeding might be done for team event so that such an example is also available readily in index.html
  - Do we need a one liner(like `window.dataLayer.push`) to inform SDK of something even if snippet is not yet on the page but would be there e.g. through GTM it would come late on the page ?

- Might be better to pass all configuration using a single base64encoded query param to booking page.

- Performance Improvements
  - Custom written Tailwind CSS is sent multiple times for different custom elements.
  
- Embed Code Generator

- Release Issues
  - Compatibility Issue - When embed-iframe.js is updated in such a way that it is not compatible with embed.js, doing a release might break the embed for some time. e.g. iframeReady event let's say get's changed to something else
    - Best Case scenario - App and Website goes live at the same time. A website using embed loads the same updated and thus compatible versions of embed.js and embed-iframe.js
    - Worst case scenario - App goes live first, website PR isn't merged yet and thus a website using the embed would load updated version of embed-iframe but outdated version of embed.js possibly breaking the embed.
    - Ideal Solution: It would be to keep the libraries versioned and embed.js should instruct app within iframe to load a particular version. But if we push a security fix, it is possible that someone is still enforcing embed to load version with security issue. Need to handle this.
    - Quick Solution: Serve embed.js also from app, so that they go live together and there is only a slight chance of compatibility issues on going live. Note, that they can still occur as 2 different requests are sent at different times to fetch the libraries and deployments can go live in between,

- UI Config Features
  - Theme switch dynamically - If user switches the theme on website, he should be able to do it on embed. Add a demo for the API. Also, test system theme handling.
    - How would the user add on hover styles just using style attribute ?

- If just iframe refreshes due to some reason, embed script can't replay the applied instructions.

- React Component
  - `onClick` support with automatic preloading
- Shadow DOM is currently in open state, which probably means that any styling change on website can possibly impact loader.

## Pending Documentation

- READMEs
  - How to make a new element configurable using UI instruction ?
  - Why do we NOT want to provide completely flexible CSS customization by adding whatever CSS user wants. ?
  - Feature Documentation
    - Inline mode doesn't cause any scroll in iframe by default. It more looks like it is part of the website.
- docs.cal.com
  - A complete document on how to use embed

- app.cal.com
  - Get Embed code for each event-type