feat(components): add support for new guide structure (#58)

* add new guide structure

* ensure backwards compatibility and refactor

* feat: add support for custom objects carousel title

* feat: update styling for shopping and category guides

* feat: update styling for comparison guides

* feat: add basic error component

* cleanup

* add js styling and deprecate objects param for headlines

* update styles

* update read mes and bundlesize

* codacy

* bundlesize

* feat: add contribution guide

* cleanup examples

* feat: add maxFeaturedItems param

* bundlesize

Author: marialungu

CONTRIBUTING.md

@@ -0,0 +1,110 @@
+Hello and welcome to the contributing guide for Generative AI Experiences. Thanks for considering participating in our project 🙇
+
+## Reporting an issue
+
+Opening an issue is very effective way to contribute because many users might also be impacted. We'll make sure to fix it quickly if it's technically feasible and doesn't have important side effects for other users.
+
+Before reporting an issue, first check that there is not an already open issue for the same topic using the [issues page](https://github.com/algolia/generative-experiences/issues). Don't hesitate to thumb up an issue that corresponds to the problem you have.
+
+## The code contribution process
+
+Generative AI Experiences is developed in TypeScript.
+
+For any code contribution, you need to:
+
+- Fork and clone the project
+- Create a new branch for what you want to solve (fix/_name-of-fix_, feat/_name-of-the-feature_)
+- Make your changes
+- Open a pull request
+
+Then:
+
+- Peer review of the pull request (by at least one of the core contributors)
+- Automatic checks (tests, commits, linters)
+- When everything is green, your contribution is merged 🚀
+
+## Commit conventions
+
+This project follows the [conventional changelog](https://conventionalcommits.org/) approach. This means that all commit messages should be formatted using the following scheme:
+
+```
+type(scope): description
+```
+
+In most cases, we use the following types:
+
+- `fix`: for any resolution of an issue (identified or not)
+- `feat`: for any new feature
+- `refactor`: for any code change that neither adds a feature nor fixes an issue
+- `docs`: for any documentation change or addition
+- `chore`: for anything that is not related to the library itself (doc, tooling)
+
+Even though the scope is optional, we try to fill it in as it helps us better understand the impact of a change. We either use the name of the package/component impacted or we use impact topic (e.g. `docs`, `tooling`, `deps`, `ci`).
+
+Finally, if your work is based on an issue on GitHub, please add in the body of the commit message "fix #1234" if it solves the issue #1234 (read "[Closing issues using keywords](https://help.github.com/en/articles/closing-issues-using-keywords)").
+
+Some examples of valid commit messages (used as first lines):
+
+> - fix(client): update getHeadlines parameters
+> - chore(deps): update dependency bundlesize to v0.18.4
+> - chore: reword contributions guides
+
+## Requirements
+
+To run this project, you will need:
+
+- Node.js ≥ 20.17 (current stable version) – [nvm](https://github.com/creationix/nvm#install-script) is recommended
+- [Yarn](https://yarnpkg.com)
+
+## Launch the dev environment
+
+First, build the libraries:
+
+```sh
+yarn build
+```
+
+Go in the relevant example package an add `.env` file, following the `.env.example`. 
+Add the information of the Algolia app you want to test the libraries on.
+
+Then start the server of the relevant example:
+
+```sh
+yarn --cwd examples/playground yarn dev
+```
+
+Finally, go to the URL displayed on the terminal (generally http://localhost:5173) to view the example in a browser.
+
+## Folders of the project
+
+Here are the main files and folders of the project.
+
+```
+▸ examples/                            << Examples, grouped per flavor
+  ▸ playground/                          << React basic example
+  ▸ playground-js/                       << JS basic example
+▸ packages/                            << Packages of the project
+  ▸ generative-experiences-api-client/   << Generative AI Experiences JS API client library
+  ▸ generative-experiences-js/           << The Generative AI Experiences JS library
+  ▸ generative-experiences-react/        << The Generative AI Experiences React library
+  ▸ generative-experiences-vdom/         << The primitives for building flavors of the Generative AI Experiences widgets
+▸ test/                                << The test utilites
+  ▸ utils/                             << Global utilities for the tests
+▸ scripts/                             << The scripts for maintaining the project
+  CHANGELOG.md                         << The autogenerated changelog (based on commits)
+  CONTRIBUTING.md                      << this file
+  package.json                         << The definition of the project
+  README.md                            << The introduction of the project
+```
+
+## Release
+
+### Main version
+
+To release a stable version, go on `master` (`git checkout master`) and use:
+
+```sh
+yarn run release
+```
+
+It will create a pull request for the next release. When it's reviewed, approved and merged, then CircleCI will automatically publish it to npm.

bundlesize.config.json

@@ -2,35 +2,35 @@
   "files": [
     {
       "path": "packages/generative-experiences-api-client/dist/index.js",
-      "maxSize": "27.59 kB"
+      "maxSize": "27.9 kB"
     },
     {
       "path": "packages/generative-experiences-api-client/dist/index.umd.js",
-      "maxSize": "11.55 kB"
+      "maxSize": "11.73 kB"
     },
     {
       "path": "packages/generative-experiences-vdom/dist/index.js",
-      "maxSize": "18.3 kB"
+      "maxSize": "4 kB"
     },
     {
       "path": "packages/generative-experiences-vdom/dist/index.umd.js",
-      "maxSize": "14.9 kB"
+      "maxSize": "3.3 kB"
     },
     {
       "path": "packages/generative-experiences-react/dist/index.js",
-      "maxSize": "19.6 kB"
+      "maxSize": "4.62 kB"
     },
     {
       "path": "packages/generative-experiences-react/dist/index.umd.js",
-      "maxSize": "15.9 kB"
+      "maxSize": "3.76 kB"
     },
     {
       "path": "packages/generative-experiences-js/dist/index.js",
-      "maxSize": "19.6 kB"
+      "maxSize": "11.3 kB"
     },
     {
       "path": "packages/generative-experiences-js/dist/index.umd.js",
-      "maxSize": "15.9 kB"
+      "maxSize": "9.57 kB"
     }
   ]
 }

examples/playground-js/index.css

@@ -0,0 +1,131 @@
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+.ais-NoWrap {
+    @apply whitespace-nowrap;
+}
+
+.ais-ScreenReaderOnly {
+    @apply sr-only;
+}
+
+/* display headlines */
+.ais-GuideHeadlinesContent-wrapper {
+    @apply rounded p-4 border border-gray-100 shadow gap-2;
+}
+
+.ais-GuideHeadlinesContent-container {
+    @apply flex flex-col items-end;
+}
+
+.ais-GuideHeadlinesContent-itemsContainer {
+    @apply flex items-center gap-6;
+}
+
+.ais-GuideHeadlinesContent-readMore {
+    @apply flex text-white py-2 mt-8 border-2 bg-blue-700 rounded-md items-center w-full justify-center;
+}
+
+.ais-GuideHeadlinesContent-item {
+    @apply bg-neutral-100 rounded p-4 space-y-3 flex justify-between min-h-[420px];
+}
+
+.ais-GuideHeadlinesContent-itemContent {
+    @apply mt-5;
+}
+
+.ais-GuideHeadlinesContent-itemTitle {
+    @apply text-blue-800 font-semibold line-clamp-2 h-12;
+}
+
+.ais-GuideHeadlinesContent-itemDescription {
+    @apply line-clamp-4 text-base mt-2;
+}
+
+.ais-GuideHeadlinesContent-itemImage {
+    @apply relative min-h-[120px] max-h-[120px] w-auto overflow-hidden mx-auto mt-4 aspect-square;
+}
+
+/* display content */
+.ais-GuideContent-contentSection {
+    @apply prose max-w-prose mx-auto px-4;
+}
+
+.ais-GuideContent {
+    @apply mb-10 w-full;
+}
+
+.ais-GuideContent-heroImage {
+    @apply mx-auto min-h-[200px] max-h-[250px] my-12;
+}
+
+.ais-GuideContent .ais-Feedback {
+    @apply flex items-end justify-end mx-auto;
+}
+
+.ais-GuideContent-factorsList {
+    @apply flex flex-wrap list-disc gap-x-2 justify-between w-full;
+}
+
+.ais-GuideContent-factorItem {
+    @apply w-[45%];
+}
+
+.ais-GuideContent-relatedItemsSection {
+    @apply prose max-w-none mx-auto px-4;
+}
+
+.ais-GuideContent-relatedItemsTitle {
+    @apply max-w-prose mx-auto px-4;
+}
+
+.ais-GuideContent-relatedItemsListContainer {
+    @apply max-w-prose mx-auto px-4;
+}
+
+.ais-GuideContent-relatedItemsList {
+    @apply p-2 flex justify-between flex-wrap list-none;
+}
+
+/* display feedback */
+.ais-Feedback {
+    @apply text-gray-500 text-base max-w-prose mt-10;
+}
+
+.ais-feedbackContainer {
+    @apply flex items-center gap-4;
+}
+
+.ais-Feedback-thanksWrapper {
+    @apply flex items-center;
+}
+
+.ais-Feedback-labelWrapper {
+    @apply flex space-x-2 items-center;
+}
+
+.ais-Feedback-labelIcon {
+    @apply h-6 w-6 flex-shrink-0;
+}
+
+.ais-Feedback-button {
+    @apply inline-block rounded font-semibold text-center shadow-sm transition-colors focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 bg-white hover:bg-white border-2 border-gray-400 hover:border-gray-500 focus-visible:outline-gray-500 text-gray-400 hover:text-gray-500 px-2.5 py-1.5;
+}
+
+.ais-Feedback-buttonsWrapper {
+    @apply flex space-x-3 items-center;
+}
+
+.ais-Feedback-buttonIcon {
+    @apply h-4 w-4 stroke-2 flex-shrink-0;
+}
+
+/* error loading guide */
+.ais-GuideContentError {
+    @apply flex flex-col items-center text-center gap-y-4 max-w-prose mx-auto my-6;
+}
+
+.ais-GuideContentErrorTitle {
+    @apply text-lg font-semibold;
+}

examples/playground-js/index.html

@@ -4,19 +4,14 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
 
     <link rel="shortcut icon" href="favicon.png" type="image/x-icon" />
-    <link
-      href="https://unpkg.com/tailwindcss@2/dist/tailwind.min.css"
-      rel="stylesheet"
-    />
-    <!-- <link rel="stylesheet" href="app.css" />
-    <link rel="stylesheet" href="Recommend.css" /> -->
+    <link rel="stylesheet" href="index.css" />
 
     <title>Algolia JavaScript GSE</title>
   </head>
 
   <body>
     <div class="container">
-      <h1>Algolia GSE</h1>
+      <h1 class="text-lg font-semibold">Algolia Generative Experiences Guides</h1>
 
       <div id="headlines"></div>
       <div id="content"></div>

examples/playground-js/package.json

@@ -22,7 +22,11 @@
   "dependencies": {
     "@algolia/generative-experiences-api-client": "1.6.0",
     "@algolia/generative-experiences-js": "1.6.0",
-    "@algolia/generative-experiences-vdom": "1.6.0"
+    "@algolia/generative-experiences-vdom": "1.6.0",
+    "@tailwindcss/typography": "^0.5.9",
+    "autoprefixer": "10.4.20",
+    "postcss": "8.4.49",
+    "tailwindcss": "3.3.2"
   },
   "devDependencies": {
     "preact": "^10.25.1"

examples/playground-js/src/index.tsx

@@ -19,13 +19,15 @@ const options = {
 };
 
 const client = createClient(options);
+/* Test JS widgets, replace 'objectID', 'category' and 'userToken' parameters */
 
 guidesHeadlines({
   container: '#headlines',
   client,
   userToken: 'test-user',
   showImmediate: true,
-  //   showFeedback: true,
+  onlyPublished: false,
+  showFeedback: true,
   category: 'category',
 });
 
@@ -41,8 +43,10 @@ guideContent<RecordType>({
   client,
   onlyPublished: false,
   itemComponent({ hit }) {
+    /* Add custom itemComponent to reflect your use case */
     return <div>{hit.title}</div>;
   },
+  showFeedback: true,
   objectID: '123',
   userToken: 'test-user',
 });

examples/playground-js/tailwind.config.js

@@ -0,0 +1,9 @@
+/** @type {import('tailwindcss').Config} */
+
+module.exports = {
+  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
+  theme: {
+    extend: {},
+  },
+  plugins: [require('@tailwindcss/typography')],
+};

examples/playground-js/vite.config.ts

@@ -1,6 +1,7 @@
 import * as path from 'path';
 
 import preact from '@preact/preset-vite';
+import tailwindcss from '@vituum/vite-plugin-tailwindcss';
 import { defineConfig } from 'vite';
 import dts from 'vite-plugin-dts';
 
@@ -11,6 +12,7 @@ export default defineConfig({
       rollupTypes: true,
     }),
     preact(),
+    tailwindcss(),
   ],
   optimizeDeps: { esbuildOptions: { jsx: 'automatic' } },
   build: {