Skip to content

Commit 86c609f

Browse files
bacaljbacalj
authored
Merge pull request #2 from necyberteam/add-web-component
Library Setup and Web Component
2 parents 692a5d4 + 37b0ee5 commit 86c609f

23 files changed

+4575
-540
lines changed

‎.babelrc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"presets": [
3+
"@babel/preset-env",
4+
["@babel/preset-react", {
5+
"runtime": "automatic"
6+
}]
7+
]
8+
}

‎.gitignore‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,3 +21,10 @@ yarn-error.log*
2121

2222
# Local Netlify folder
2323
.netlify
24+
25+
# local diffs
26+
*.diff
27+
*.patch
28+
29+
# Library build output
30+
/dist

‎.npmignore‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Development files
2+
node_modules
3+
*.log
4+
.DS_Store
5+
.env
6+
.env.local
7+
.env.development.local
8+
.env.test.local
9+
.env.production.local
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
14+
# Development configs
15+
.gitignore
16+
.eslintrc
17+
.prettierrc
18+
19+
# Source files that aren't needed in the final package
20+
src/setupTests.js
21+
src/reportWebVitals.js
22+
src/logo.svg
23+
24+
# Example files
25+
example
26+
27+
# Documentation and misc
28+
CHANGELOG.md
29+
*.diff
30+
*.patchFile

‎README.md‎

Lines changed: 158 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,181 @@
1-
# ACCESS Q&A Tool Widget
1+
# ACCESS Q&A Bot
22

3-
This REACT app provides an interface to the ACCESS Q&A Tool API. More information about this tool is available at https://support.access-ci.org/tools/access-qa-tool.
3+
A React component and Web Component for integrating the ACCESS Q&A Bot into your application.
44

5-
Interacting with the Q&A Tool requires authentication with an ACCESS ID. Currently, the app checks for the class "user-logged-in" on the <body> HTML element to determine if a visitor is authenticated.
5+
## Installation
66

7-
The Q&A Tool API requires an API Key to be sent in the HTTP Headers. This should be set with the `REACT_APP_API_KEY` environment variable. Please contact ACCESS Support if you need an API Key.
7+
```bash
8+
npm install @snf/access-qa-bot
9+
```
10+
11+
## Usage
12+
13+
### As a React Component
14+
15+
```jsx
16+
import React, { useState } from 'react';
17+
import { QABot } from 'access-qa-bot';
18+
19+
function MyApp() {
20+
const [isOpen, setIsOpen] = useState(false);
21+
const isLoggedIn = true; // Determine based on your auth logic
22+
23+
return (
24+
<div className="app">
25+
<h1>My React Application</h1>
26+
27+
<button onClick={() => setIsOpen(!isOpen)}>
28+
{isOpen ? 'Close' : 'Open'} Q&A Bot
29+
</button>
30+
31+
<QABot
32+
isLoggedIn={isLoggedIn}
33+
isOpen={isOpen}
34+
onClose={() => setIsOpen(false)}
35+
welcome="Welcome to the ACCESS Q&A Bot!"
36+
prompt="How can I help you today?"
37+
apiKey={process.env.REACT_APP_API_KEY}
38+
/>
39+
</div>
40+
);
41+
}
42+
```
43+
44+
### As a Web Component
45+
46+
#### Method 1: Using HTML directly
47+
48+
```html
49+
<script src="https://unpkg.com/@snf/[email protected]/dist/access-qa-bot.standalone.js"></script>
50+
51+
<access-qa-bot
52+
welcome="Welcome to the Q&A Bot!"
53+
prompt="Ask me anything about ACCESS..."
54+
is-logged-in
55+
is-open>
56+
</access-qa-bot>
57+
```
858

9-
Some messages in the app can be customized if desired:
10-
- welcome message
11-
- prompt
59+
#### Method 2: Creating programmatically
60+
61+
```html
62+
<script src="https://unpkg.com/@snf/[email protected]/dist/access-qa-bot.standalone.js"></script>
63+
64+
<div id="qa-container"></div>
65+
66+
<script>
67+
const container = document.getElementById('qa-container');
68+
const qaBot = document.createElement('access-qa-bot');
69+
qaBot.setAttribute('welcome', 'Hello!');
70+
qaBot.setAttribute('prompt', 'Ask something...');
71+
qaBot.setAttribute('is-logged-in', '');
72+
container.appendChild(qaBot);
73+
</script>
74+
```
75+
76+
#### Method 3: Using the JavaScript API
77+
78+
```html
79+
<script src="https://unpkg.com/@snf/[email protected]/dist/access-qa-bot.standalone.js"></script>
80+
81+
<div id="js-api-container"></div>
82+
83+
<script>
84+
window.addEventListener('load', function() {
85+
if (window.accessQABot && window.accessQABot.qAndATool) {
86+
window.accessQABot.qAndATool({
87+
target: document.getElementById('js-api-container'),
88+
welcome: "This is created using the JavaScript API!",
89+
prompt: "Ask a question about ACCESS...",
90+
isLoggedIn: true,
91+
embedded: true,
92+
isOpen: true
93+
});
94+
}
95+
});
96+
</script>
97+
```
1298

13-
See the index.html file for examples of how to add the default widget floating in the bottom right of the page and as an "embedded" widget with the tool open on the page by default.
99+
### Direct Deployment via jsDelivr CDN
14100

15-
## Deployment
16-
You can install the app in a website:
101+
For websites that don't use npm packages, you can directly include the ACCESS Q&A Bot using jsDelivr CDN:
17102

18103
```html
19-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/necyberteam/qa-bot@v0.1.1/build/static/css/main.css">
104+
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/necyberteam/qa-bot@v0.2.0/build/static/css/main.css">
20105
<div style="display:none;" id="qa-bot">
21106
&nbsp;
22107
</div>
23-
<script src="https://cdn.jsdelivr.net/gh/necyberteam/[email protected]/build/static/js/main.js"></script><script src="https://cdn.jsdelivr.net/gh/necyberteam/[email protected]/build/static/js/453.chunk.js"></script>
108+
<script src="https://cdn.jsdelivr.net/gh/necyberteam/[email protected]/build/static/js/main.js"></script>
109+
<script src="https://cdn.jsdelivr.net/gh/necyberteam/[email protected]/build/static/js/453.chunk.js"></script>
24110
```
25111

26-
## Available Scripts
112+
Replace `v0.2.0` with the specific version you want to use. This method provides the React version of the bot and automatically initializes it when the page loads.
27113

28-
In the project directory, you can run:
114+
## Properties
29115

30-
### `npm start`
116+
| Property | Type | Description |
117+
|----------|------|-------------|
118+
| welcome | string | Welcome message shown to the user |
119+
| prompt | string | Text shown in the input field |
120+
| embedded | boolean | Display in embedded mode |
121+
| isLoggedIn / is-logged-in | boolean | Whether the user is logged in |
122+
| disabled | boolean | Disable the chat input |
123+
| isOpen / is-open | boolean | Whether the chat is open |
124+
| apiKey / api-key | string | API key for authentication |
125+
| onClose | function | Callback when the chat is closed (React only) |
31126

32-
Runs the app in the development mode.\
33-
Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
127+
## Events
34128

35-
The page will reload when you make changes.\
36-
You may also see any lint errors in the console.
129+
When using as a Web Component, you can listen for the following events:
37130

38-
### `npm test`
131+
```javascript
132+
document.querySelector('access-qa-bot').addEventListener('qabot-close', () => {
133+
console.log('Chat was closed');
134+
});
135+
```
136+
137+
## Disambiguating all the different html files here
138+
139+
- **index.html**: The main demo file showcasing React-based integration methods with three different approaches to integrate the QA Bot: auto-mounting to a specific div ID, using class-based selectors, and explicitly calling the JavaScript function.
140+
141+
- **public/index.html**: The standard React application template file created by Create React App. This serves as the base HTML template that gets processed during the React build process.
142+
143+
- **build/index.html**: The minified production version of the public/index.html file after the build process has completed. This contains all the necessary script and link tags to load the compiled React application.
144+
145+
- **demo.html**: A standalone demo specifically showcasing the Web Component implementation (using the custom `<access-qa-bot>` element). This demonstrates three integration methods: standard floating button, embedded mode, and using the JavaScript API with the Web Component.
146+
147+
The **index.html** file is focused on the React component usage, while **demo.html** focuses on the Web Component usage, providing complete examples for both integration approaches.
148+
149+
## Development and Testing
150+
151+
### Development Server
152+
When running the default development script (`npm start` or `yarn start`), the application serves the content from the `public` directory using React's development server. This shows the default React implementation with hot reloading enabled. Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
153+
154+
```bash
155+
# Start the development server (React implementation)
156+
npm start
157+
```
158+
159+
### Testing Standalone Demo Files
160+
To test the standalone demo files (`index.html` and `demo.html`) at the root level, you need to:
161+
162+
1. Stop the development server (if running)
163+
2. Build the project (`npm run build`)
164+
3. Serve the root directory using a static file server:
165+
166+
```bash
167+
# After building, serve the files from root
168+
npx serve
169+
```
39170

40-
Launches the test runner in the interactive watch mode.\
41-
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
171+
Then you can access:
172+
- The React demo at `/index.html` (or just `/`)
173+
- The Web Component demo at `/demo.html`
42174

43-
### `npm run build`
175+
This allows testing both integration approaches (React components and Web Components) in their respective demo environments.
44176

45-
Builds the app for production to the `build` folder.\
46-
It correctly bundles React in production mode and optimizes the build for the best performance.
177+
Note: The standalone demos rely on the built files in the `dist` and `build` directories, so make sure to build the project before testing.
47178

48-
The build is minified and the filenames include the hashes.\
49-
Your app is ready to be deployed!
179+
## Browser Support
50180

51-
See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
181+
The Web Component implementation uses modern browser features. For older browsers, consider using a polyfill.

‎build/static/js/453.chunk.js‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)