@tulipnpm/timekit_project_selector 2.1.2 → 2.1.3-rc.1

package/.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+  "context": {
+    "fileName": "AGENTS.md"
+  }
+}

package/AGENTS.md

@@ -0,0 +1,47 @@
+# Project Context: Tulip Appointments Web Widget
+
+## Overview
+The Tulip Appointments Web Widget (`@tulipnpm/timekit_project_selector`) is a JavaScript library that extends the functionality of [TimeKit's Booking Widget](https://developers.timekit.io/docs/booking-widget-v2). It allows users to set up selectors based on project metadata to filter TimeKit projects for customer bookings. It supports a default UI (Popup or Page mode) and a Custom UI mode.
+
+## Tech Stack
+- **Language:** JavaScript (ES6+)
+- **Build Tool:** Webpack (^5.14.0)
+- **Testing Framework:** Jest (^26.6.3)
+- **Transpilation:** Babel
+- **Key Dependencies:** `axios` (^0.21.1), `lodash` (^4.17.20), `@babel/runtime` (^7.12.5)
+- **Key DevDependencies:** `webpack` (^5.14.0), `jest` (^26.6.3), `babel-loader` (^8.2.2)
+
+## Project Structure
+- **`src/`**: Core source code.
+    - **`ConfigurationManager.js`**: Manages widget configurations.
+    - **`TimekitApiClient.js`**: Client for interacting with TimeKit API.
+    - **`Strategy/`**: Contains strategies for project selection (e.g., `DefaultProjectStrategy`, `LocationsStrategy`).
+    - **`Steps/`**: Logic for widget steps (`Step.js`, `StepsFactory.js`).
+    - **`ui/`**: UI components (`widget.js`, `searchbar.js`, `embed.js`, etc.).
+    - **`styles/`**: CSS files for the widget.
+    - **`callbacks/`**: Logic for specific callbacks (e.g., auto-assigning associates).
+- **`test/`**: Test files.
+    - **`unittests/`**: Jest unit tests corresponding to source files.
+    - **`data/`**: Mock data for tests.
+    - HTML files (`custom.html`, `embed.html`, `index.html`) for testing different modes.
+- **`dist/`**: Distribution files (built artifacts).
+
+## Key Scripts
+- **Build:** `npm run build` (runs `webpack`)
+- **Development Server:** `npm run start-dev` (runs `webpack serve --mode development`)
+- **Test:** `npm test` (runs `jest`)
+- **CI Test:** `npm run test:ci` (runs jest with coverage and CI reporters)
+- **Watch:** `npm run watch` (runs `webpack --watch`)
+
+## Development Conventions
+- **Code Style:** Follows standard JavaScript conventions.
+- **Testing:** Unit tests are located in `test/unittests` and mirror the structure of `src`.
+- **Building:** The project uses Webpack to bundle the library for distribution.
+- **Configuration:** Project configurations are managed via `ConfigurationManager`.
+
+## Gotchas & Implementation Details
+- **External Dependencies:** The library relies on `TimekitBooking` being available in the global scope (provided by TimeKit's `booking.min.js`). It is not imported via `npm`.
+- **Symbol Typos:** Note that "Strategy" is misspelled as "Statergy" in several key symbols, including the file `src/Strategy/ServiceProjectsStatergy.js` and its corresponding class name.
+- **Template Resolution:** Card rendering uses a custom template parser in `src/ui/helpers.js` that resolves placeholders like `{{[meta]key}}` or `{{[project]key}}`.
+- **State Management:** The application uses a custom singleton store (`src/ProjectsStore.js`) to manage the state of fetched projects and active filters.
+- **CSS Injection:** Styles are imported in `src/index.js` and injected into the DOM at runtime, typically using Webpack's `style-loader`.

package/README.md

@@ -2,14 +2,55 @@
 
 The Tulip Appointments Web Widget is a library that extends the functionality of [TimeKit's Booking Widget](https://developers.timekit.io/docs/booking-widget-v2). This library allows users to set up selectors based on project metadata, which will filter down a list of TimeKit projects for a customer to book with. The library has a default UI that embeds on an e-commerce site that can either be customized or overwritten.
 
-## Installation
+## Integrator Installation
+
+If you are looking to add the Tulip Appointments Web Widget to your website, follow these steps:
 
 ```html
+<!-- 1. Required: Timekit's base booking styles -->
 <link rel="stylesheet" href="https://cdn.timekit.io/booking-js/v3/booking.min.css" />
+
+<!-- 2. Required: Timekit's base booking library (Provides the global TimekitBooking constructor) -->
 <script type="text/javascript" src="//cdn.timekit.io/booking-js/v3/booking.min.js" defer></script>
+
+<!-- 3. Required: This library (Tulip Project Selector) -->
 <script src="https://cdn.jsdelivr.net/npm/@tulipnpm/timekit_project_selector@latest/dist/timekit_project_selector.min.js"></script>
 ```
 
+Alternatively, if you are using a module bundler, you can install both via npm:
+`npm install @timekit/booking-js @tulipnpm/timekit_project_selector`
+
+---
+
+## Developer Setup
+
+If you are a developer working on the `timekit-ecomm-widget` repository itself, follow these steps to get started:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone git@git.internal.tulip.io:teams/apps/connect/timekit-ecomm-widget.git
+    cd timekit-ecomm-widget
+    ```
+2.  **Install dependencies:**
+    ```bash
+    npm install
+    ```
+3.  **Local Development:**
+    To run the development server with hot-reloading:
+    ```bash
+    npm run start-dev
+    ```
+4.  **Testing:**
+    ```bash
+    npm test
+    ```
+5.  **Build for Production:**
+    ```bash
+    npm run build
+    ```
+
+---
+
 ## Initialization
 
 To initialize the Tulip Appointments Web Widget on your site, you first need to import all required libraries onto your webpage (see above). After the library is installed, set up is as easy as running a single function:
@@ -25,6 +66,16 @@ timekit_project_selector.init({
 
 This will connect to TimeKit's API and load in all the required data. Once the initialization is completed, the exposed methods will be able to be used. If enabled, it will also render the default UI.
 
+### TimekitBooking Dependency
+
+This library does not bundle the core Timekit booking logic. It relies on the global `TimekitBooking` constructor, which is provided by the **Timekit Booking JS library** mentioned in the [Installation](#installation) section.
+
+You can provide this dependency in two ways:
+1.  **CDN (Recommended for simple integration):** Include the `booking.min.js` script tag.
+2.  **NPM:** Install `@timekit/booking-js`. If using NPM, ensure that `TimekitBooking` is available on the `window` object, as this library looks for the global variable when a project is selected.
+
+The `selectProject` method internally initializes a new `TimekitBooking` instance to render the final calendar view. Without this dependency, the widget will fail at the final step.
+
 ---
 
 ## Configurations
@@ -283,7 +334,7 @@ timekit_project_selector.init({
 
 ### Automatically Assign Associates To Bookings (Optional)
 
-Once bokings are created associates must be manually assigned to those bookings. This automatically assigns assigns associates when bookings are created. To automatically assign associates to bookings the `shouldAutomaticallyBookAssociates` configuration option can be set to `true`. 
+Once bookings are created associates must be manually assigned to those bookings. This automatically assigns associates when bookings are created. To automatically assign associates to bookings the `shouldAutomaticallyBookAssociates` configuration option can be set to `true`. 
 
 ```js
 timekit_project_selector.init({
@@ -340,9 +391,7 @@ timekit_project_selector.getStrategy('store_project');
 ```
 #### getProjects()
 
-Returns a list of TimeKit projects
-Optionally takes project type for return projects by project type only.(Filters not using if null)
-Optionally takes filters for return filtered projects
+Returns a list of TimeKit projects. Accepts an optional `filters` object to filter the results.
 
 ```js
 await timekit_project_selector.getStrategy('store_project').getProjects({ id: 'ef0cee8a-6096-453f-a634-1597b359cdfa'});
@@ -381,6 +430,20 @@ Opens the BookingJS widget for the selected project. Takes a TimeKit Project as
 timekit_project_selector.selectProject(timekitProject);
 ```
 
+### getStepsFactory
+
+Returns the steps factory instance which helps track the state of selection steps.
+
+```js
+timekit_project_selector.getStepsFactory();
+```
+
+---
+
+## Architecture
+
+For a detailed breakdown of how the widget manages project selection logic and wizard steps, see the [Strategies and Steps Architecture](docs/STRATEGIES_AND_STEPS.md) documentation.
+
 ## Supported Use Cases (Default UI)
 ### Global Appointment Type -> Store -> Booking.js
 ```js
@@ -499,10 +562,6 @@ timekit_project_selector.selectProject(timekitProject);
             let serviceHtml = '';
             let locationHtml = '';
 
-            // You could use simple array instead of using the steps factor.
-            // This factory makes it simple to track which TK project uuids were selected
-            let stepsFactory = tps.getStepsFactory();
-
             // Fetch the service_project
             let globalProjects = await tps.getStrategy('service_project').getProjects({ t_private: 0, t_disabled: 0 });