@financial-times/qanda-ui 0.0.1-beta.1

package/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "singleQuote": true
+}

package/.toolkitrc.yml

@@ -0,0 +1,34 @@
+plugins:
+  - '@dotcom-tool-kit/component'
+  - '@dotcom-tool-kit/jest'
+  - '@dotcom-tool-kit/webpack'
+  - '@dotcom-tool-kit/node'
+commands:
+  test:local:
+    - Jest
+  test:ci:
+    - Jest
+  build:local:
+    - Webpack
+  run:local:
+    - Webpack
+    - Node
+  publish:tag:
+    - NpmPublish
+options:
+  plugins:
+    dotcom-tool-kit:
+      allowNativeFetch: true
+    '@dotcom-tool-kit/circleci':
+      cimgNodeVersions:
+        - '22.4'
+        - '23.9'
+  tasks:
+    Jest:
+      configPath: jest.config.js
+    Webpack:
+      configPath: webpack.prod.js
+      envName: production
+    Node:
+      entry: server.js
+      useDoppler: false

package/.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "editor.tabSize": 2,
+  "editor.detectIndentation": false
+}

package/CODEOWNERS

@@ -0,0 +1,3 @@
+# See https://help.github.com/articles/about-codeowners/ for more information about this file.
+
+* @financial-times/storytelling

package/README.md

@@ -0,0 +1,161 @@
+# QandA-UI
+
+A library for the Live Q&A client-side component
+
+## Features
+
+## Usage
+
+This library exports a class which can be used to construct a new instance of QandaUI and exposes methods to initialise that and to destroy it.
+
+You can pass the necessary settings to Qanda UI in either the JS or in the container element.
+
+### Example:
+
+```jsx
+<div class="qanda"></div>
+```
+
+```js
+import QandaUI from '@financial-times/qanda-ui';
+
+const qandaEl = document.querySelector('.qanda');
+const qandaUI = new QandaUI(qandaEl, {
+  storyId: '71539bd7-1818-4193-8a58-d5a4d914a012',
+  useStaging: true,
+  title: 'Lorem ipsum title',
+  commentsAPIHost: 'https://comments-api-local.ft.com',
+  commentsAPIVersion: 'v1',
+});
+qandaUI.init();
+```
+
+Alternatively
+
+```jsx
+<div
+  class="qanda"
+  data-qanda-storyId="71539bd7-1818-4193-8a58-d5a4d914a012"
+  data-qanda-useStaging="true"
+  data-qanda-title="Article title"
+  data-qanda-commentsAPIHost="https://comments-api.ft.com"
+  data-qanda-commentsAPIVersion="v1"
+></div>
+```
+
+```js
+import QandaUI from '@financial-times/qanda-ui';
+const qandaEl = document.querySelector('.qanda');
+const qandaUI = new QandaUI(qandaEl);
+qandaUI.init();
+```
+
+### Parameters
+
+- storyId: (required) string, the ID of the article used for Live Q&A
+- useStaging: (optional) boolean, set to true if you want to use the staging Coral
+- title: (required) string, the article title, needed to set up Coral properly
+- commentsAPIHost: (required) string, the host of the API to be used (include the protocol)
+- commentsAPIVersion: (required) string, the version of the API to be used
+
+### Instance Methods
+
+- `myInstance.init()` - render the Qanda UI
+- `myInstance.destroy()` - remove the Qanda instance
+
+## Development
+
+### Prerequisites
+
+- Node.js
+- npm
+
+### Installation
+
+```sh
+npm install
+```
+
+### Running the Development Environment
+
+To start the development server, run:
+
+```sh
+npm run dev
+```
+
+This will start the server on `https://local.ft.com:3005`.
+
+Add on `?storyID=somestoryID` to show the details for a particular article.
+
+### Customization
+
+You can customize the demo application by modifying the configuration files in the `demo/config.ts` or altering the settings in `demo/index.jsx`.
+
+These are the config settings you can work with:
+
+- `export const USE_STAGING = true;` // use Coral staging or production
+- `export const USE_LOCAL_API = true;` // use local next-comments-api or live
+- `export const MOCK_SSE = true;` // use a dummy eventsource that lets you send mock events rather than listen to ones coming from next-comments-api
+
+### Building and Running the Production Server
+
+To build the project and run it via Express, run:
+
+```sh
+npm run build && npm start
+```
+
+This will start the server on `http://local.ft.com:3005`.
+
+### Running Tests
+
+To run the Jest tests, use:
+
+```sh
+npm run test
+```
+
+## Technology
+
+This uses React, Redux and RTK Query to create the components and manage their states.
+
+- RTK Query is used for API calls to `next-comments-api`.
+- The store is used for non-API data that needs to be shared around the components
+- The story ID and useStaging settings passed in when the Qanda compontent is set are saved into the Context.
+
+### How updates work
+
+In order to receive updates from the next comments API, we use an EventSource that listens to an EventEmitter endpoint on next-comments-api.
+
+It is very similar to the process used in `next-live-event-api` for live blogs updates.
+
+For full details, see https://github.com/Financial-Times/next-comments-api/blob/main/docs/liveqa.md#qanda-and-next-comments-api
+
+When a new comment relevant to the Q&A is posted, Coral will send out a message via a webhook to the next-comments API.
+
+The next-comments API will then fetch the rest of the data for the comments and publish the data to any listening clients.
+
+## Project Structure
+
+- `src/`: Contains the source code for the application.
+  - `components/`: React components used in the application.
+  - `store/`: Redux store configuration and slices.
+  - `client/`: Client-side utilities and configurations.
+  - `utils/`: Utility functions.
+  - `types/`: TypeScript type definitions.
+- `dist/`: The output directory for the built project.
+- `__mocks__/`: Mock data for testing.
+
+## Contributing
+
+1. Open a PR with your changes against the `main` branch
+2. Get an approval from someone from your team
+3. Ask for a StoryTelling team review in #storytelling-support
+4. Once merged, tag a version in github and a new version of the package will be automatic released
+5. Open a PR in next-article and one in FT-App with the latest version
+6. Ask for a review from StoryTelling in #storytelling-support
+
+## License
+
+This project is licensed under the MIT License.

package/babel.config.json

@@ -0,0 +1,10 @@
+{
+  "presets": [
+    "@babel/preset-typescript",
+    ["@babel/preset-env", { "targets": ">= 1%, not dead" }],
+    [
+      "@babel/preset-react",
+      { "runtime": "automatic", "importSource": "preact" }
+    ]
+  ]
+}

package/dist/index.html

@@ -0,0 +1,4 @@
+<!doctype html><html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/><title>Live Q&A UI</title><style>.app-container {
+        text-align: center;
+        padding: 80px 20px;
+      }</style></head><body><div id="root" class="app-container"></div><script defer="defer" src="index.js"></script></body></html>