acinguiux-preact-components 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,535 @@
+# acinguiux-preact-components
+
+A Preact component library providing atoms, molecules, organisms, and web components for building branded digital experiences across multiple themes.
+
+**Package size:** ~663 kB (tarball) · **Unpacked:** ~1.4 MB · **20 built-in themes**
+
+---
+
+## Installation
+
+```bash
+npm install acinguiux-preact-components
+```
+
+> **Peer dependency:** Preact `^10.28.2` must be installed in your project.
+
+```bash
+npm install preact
+```
+
+---
+
+## Import Paths
+
+| Import path | What it provides |
+|---|---|
+| `acinguiux-preact-components` | Core utilities (routing, renderer, consent, i18n, etc.) |
+| `acinguiux-preact-components/matter` | All UI components (atoms, molecules, organisms) |
+| `acinguiux-preact-components/preact` | Re-exported Preact |
+| `acinguiux-preact-components/preact/hooks` | Re-exported Preact hooks |
+
+---
+
+## Quick Start
+
+```js
+import { renderPage } from 'acinguiux-preact-components'
+import { Page, Container, Heading } from 'acinguiux-preact-components/matter'
+import { h } from 'acinguiux-preact-components'
+```
+
+### Apply a Theme
+
+Copy the theme CSS from `node_modules/acinguiux-preact-components/src/content/themes/` into your build, or reference it directly:
+
+```html
+<link rel="stylesheet" href="./node_modules/acinguiux-preact-components/src/content/themes/theme-base2/theme-base2.css">
+```
+
+---
+
+## Core API (`acinguiux-preact-components`)
+
+### Rendering
+
+| Export | Description |
+|---|---|
+| `renderPage(model, el)` | Render a full page component into a DOM element |
+| `renderComponent(model, el)` | Render a single component into a DOM element |
+
+### Routing
+
+| Export | Description |
+|---|---|
+| `dataset` | Access the current page dataset |
+| `componentModels` | Map of registered component models |
+| `ValidationError` | Error class for model validation failures |
+
+### Utilities
+
+| Export | Description |
+|---|---|
+| `h` | Preact `h` (JSX factory) |
+| `t(key)` | i18n translation helper |
+| `i18n` | i18n configuration object |
+| `tw(classes)` | Twind utility-first class helper |
+| `injectStyles(css)` | Inject styles into the document |
+| `LARGE`, `MEDIUM` | Breakpoint constants for `tw` |
+| `getUserId()` | Get anonymous analytics user ID |
+| `getConsent()` | Get current consent state |
+| `setConsent(value)` | Set consent state |
+| `waitForConsent()` | Promise that resolves when consent is granted |
+| `deepSelector` | Deep DOM selector utility |
+| `register(name, component)` | Register a web component |
+| `customElement` | Custom element decorator/helper |
+
+---
+
+## Components (`acinguiux-preact-components/matter`)
+
+### Atoms
+
+Basic building blocks with no dependencies on other components.
+
+| Component | Description |
+|---|---|
+| `Audio` | Audio player element |
+| `Box` | Generic container box |
+| `Button` | Styled button |
+| `Card` | Card container |
+| `Form` | Form wrapper |
+| `Heading` | Heading with configurable level |
+| `Icon` | SVG icon renderer |
+| `Img` | Responsive image |
+| `Input` | Form input field |
+| `Link` | Anchor link |
+| `LinkText` | Inline text link |
+| `List` | Ordered / unordered list |
+| `Logo` | Brand logo |
+| `Menu` | Navigation menu |
+| `Message` | Alert / status message |
+| `NavLink` | Navigation link with active state |
+| `Popup` | Modal / popup overlay |
+| `RichText` | HTML rich text renderer |
+| `Scroller` | Horizontal scroll container |
+| `SVG` | Raw SVG renderer |
+| `Table` | Data table |
+| `Time` | Formatted date/time |
+| `Video` | Video player element |
+
+### Molecules
+
+Composed of atoms.
+
+| Component | Description |
+|---|---|
+| `Asset` | File / media asset display |
+| `Glossary` | Term and definition list |
+| `Links` | Group of links |
+| `PromoText` | Promotional text block |
+| `Tags` | Tag / label list |
+| `Tree` | Hierarchical tree view |
+
+### Organisms
+
+Full-featured page sections.
+
+| Component | Description |
+|---|---|
+| `AccordionItem` | Collapsible accordion section |
+| `Author` | Author bio block |
+| `Breadcrumb` | Page breadcrumb trail |
+| `CallToAction` | CTA block |
+| `Carousel` | Image / content carousel |
+| `Cart` | Shopping cart |
+| `CartItem` | Single cart item |
+| `ContactForm` | Contact form with validation |
+| `Container` | Page section container |
+| `ContentOwner` | Content ownership metadata |
+| `DateEntry` | Date input group |
+| `ExternalSearch` | External search integration |
+| `FilteredItem` | Filterable list item |
+| `FooterItem` | Footer link / content block |
+| `ImageGallery` | Image gallery grid |
+| `LastModified` | Last-modified date display |
+| `LegalFooter` | Legal / compliance footer |
+| `ListItem` | Styled list item |
+| `Metadata` | Page metadata block |
+| `Navigation` | Site navigation |
+| `Notification` | Toast / notification banner |
+| `OrderTracker` | Order status tracker |
+| `Page` | Full page shell (handles favicons, theme, analytics) |
+| `PageHeader` | Page title header |
+| `PageHeaderBanner` | Hero banner header |
+| `PageTags` | Page taxonomy tags |
+| `PressRelease` | Press release layout |
+| `ProductAdmin` | Product admin panel |
+| `PromoBanner` | Full-width promo banner |
+| `PromoBottom` | Bottom-of-page promo |
+| `PromoButton` | Button-style promo |
+| `PromoCard` | Card-style promo |
+| `PromoCardCover` | Full-cover promo card |
+| `PromoFull` | Full-page promo layout |
+| `PromoImage` | Image-led promo block |
+| `PromoLure` | Teaser / lure promo |
+| `PromoProductCard` | Product promo card |
+| `PromoProductFull` | Full product promo |
+| `PromoSimple` | Minimal promo block |
+| `Quote` | Pull quote |
+| `SearchForm` | Search input form |
+| `SearchNav` | Search with navigation |
+| `SearchResult` | Single search result |
+| `Slider` | Slide / range input |
+| `StandaloneAsset` | Full-page asset display |
+| `Tabs` | Tabbed content panel |
+| `Topbar` | Site top bar |
+| `WebComponent` | Generic web component wrapper |
+
+### Routing
+
+| Export | Description |
+|---|---|
+| `Component` | Base component class for routing |
+| `Router` | Client-side router |
+
+---
+
+## Web Components (`src/wcs/components`)
+
+Pre-built custom elements for embedding third-party integrations and self-contained widgets. Register and use via `<acinguiux-*>` tags.
+
+| Component | Tag / File | Description |
+|---|---|---|
+| `BazaarVoice` | `bazaar-voice.js` | Bazaarvoice reviews integration |
+| `ChatbotKoreai` | `chatbot-koreai.js` | Kore.ai chatbot |
+| `ChatbotMs` | `chatbot-ms.js` | Microsoft chatbot |
+| `ComparisonChart` | `comparison-chart.js` | Side-by-side comparison chart |
+| `ConsentBanner` | `consent-banner.js` | GDPR / consent management banner |
+| `DecisionTree` | `decision-tree.js` | Interactive decision tree |
+| `DynamicContactDetails` | `dynamic-contact-details.js` | Location-aware contact details |
+| `FloatingButton` | `floating-button.js` | Floating action button |
+| `FormstackForm` | `formstack-form.js` | Formstack form embed |
+| `FuelPrices` | `fuel-prices.js` | Live fuel price display |
+| `FurnitureOverview` | `furniture-overview.js` | Furniture product overview |
+| `GaugeValue` | `gauge-value.js` | Gauge / metric display |
+| `HelpCentre` | `help-centre.js` | Help centre widget |
+| `ImageGen` | `image-gen.js` | AI image generation widget |
+| `InspiredGallery` | `inspired-gallery.js` | Curated image gallery |
+| `LaunchContainer` | `launch-container.js` | App launch container |
+| `LngMap` | `lng-map.js` | LNG station map |
+| `MouseflowAnalytics` | `mouseflow-analytics.js` | Mouseflow session recording |
+| `MsdsSearch` | `msds-search.js` | MSDS / safety data search |
+| `ProductCatalogue` | `product-catalogue.js` | Product catalogue browser |
+| `ProductLinks` | `product-links.js` | Related product links |
+| `RioIframe` | `rio-iframe.js` | RIO iframe embed |
+| `SalsifyProducts` | `salsify-products.js` | Salsify product data |
+| `ShoutOut` | `shout-out.js` | Highlighted callout block |
+| `SimpleChart` | `simple-chart.js` | Lightweight chart |
+| `SingleStat` | `single-stat.js` | Single metric / KPI display |
+| `SiteFeedback` | `site-feedback.js` | User feedback widget |
+| `SkdsSearch` | `skds-search.js` | SKDS search integration |
+| `SmartBanner` | `smart-banner.js` | Mobile app smart banner |
+| `StandaloneTable` | `standalone-table.js` | Standalone data table |
+| `StationLocator` | `station-locator.js` | Fuel station locator |
+| `StoreBadges` | `store-badges.js` | App Store / Play Store badges |
+| `TopbarButton` | `topbar-button.js` | Topbar action button |
+| `ZendeskChat` | `zendesk-chat.js` | Zendesk live chat widget |
+
+---
+
+## Themes
+
+20 pre-built themes are included under `src/content/themes/`. Each theme provides:
+
+- **CSS custom properties** for colors, typography, spacing, and logo ratios
+- **Web fonts** (shared from `theme-base2` — one copy, all themes reference it)
+- **Favicon set** (unique branding for `theme-vegetable`, `theme-aurvana`, `theme-nam-2025`; all others share `theme-base2`)
+
+| Theme | Directory |
+|---|---|
+| Base | `theme-base` |
+| Base 2 *(default / shared assets)* | `theme-base2` |
+| AMG | `theme-acinguiux-amg` |
+| Café | `theme-acinguiux-cafe` |
+| Energy | `theme-acinguiux-energy` |
+| Livewire | `theme-acinguiux-livewire` |
+| Livewire Italy | `theme-acinguiux-livewire-italy` |
+| Recharge | `theme-acinguiux-recharge` |
+| Allon | `theme-allon` |
+| Atlas | `theme-atlas` |
+| Aurvana | `theme-aurvana` |
+| Eco-Marathon | `theme-eco-marathon` |
+| Energy Transition Campus Amsterdam | `theme-energy-transition-campus-amsterdam` |
+| EVPass | `theme-evpass` |
+| NAM 2025 | `theme-nam-2025` |
+| Pennzoil | `theme-pennzoil` |
+| Quaker State | `theme-quaker-state` |
+| Tafawoq | `theme-tafawoq` |
+| Vegetable | `theme-vegetable` |
+| Zeolyst | `theme-zeolyst` |
+
+### Using a Theme
+
+```js
+// Dynamically apply a theme at runtime (handled by the Page component)
+// Set the theme path via the page model's links:
+const model = {
+  links: [
+    { name: 'theme', value: '/themes/theme-base2' }
+  ]
+}
+```
+
+Or reference the CSS directly in your HTML:
+
+```html
+<link rel="stylesheet" href="path/to/themes/theme-base2/theme-base2.css">
+```
+
+---
+
+## Build Scripts
+
+| Script | Command | Description |
+|---|---|---|
+| `start` | `npm start` | Build in watch/dev mode |
+| `build` | `npm run build` | Production build |
+| `pack:check` | `npm run pack:check` | Dry-run pack (see included files) |
+| `pack:check:size` | `npm run pack:check:size` | Validate package stays under size limit |
+
+---
+
+## Testing
+
+Tests are written with [Playwright](https://playwright.dev/) and run against the locally built dev server. 88 spec files cover all atoms, molecules, organisms, and web components.
+
+### Run tests
+
+```bash
+# Start the dev server in a separate terminal first
+npm start
+
+# Then in another terminal
+npm test
+```
+
+### Environment variables (`.env`)
+
+| Variable | Default | Description |
+|---|---|---|
+| `DEV_HOSTNAME` | `localhost` | Dev server hostname |
+| `DEV_PORT` | `3000` | Dev server port |
+| `TEST_CONCURRENCY` | `4` | Parallel worker count |
+| `TEST_TIMEOUT` | `30000` | Per-test timeout (ms) |
+| `TEST_USER` | `admin` | Admin user for auth tests |
+| `TEST_PASS` | `admin` | Admin password for auth tests |
+
+Create a `.env` file in the project root to override defaults:
+
+```
+DEV_PORT=3001
+TEST_CONCURRENCY=2
+```
+
+### Test files
+
+<details>
+<summary>88 spec files</summary>
+
+| Spec file | Area |
+|---|---|
+| `ab-test.spec.js` | A/B testing |
+| `accordion.spec.js` | Accordion organism |
+| `analytics.spec.js` | Adobe Analytics integration |
+| `anchors.spec.js` | Anchor link behaviour |
+| `author.spec.js` | Author organism |
+| `bazaar-voice.spec.js` | BazaarVoice web component |
+| `breadcrumb.spec.js` | Breadcrumb organism |
+| `call-to-action.spec.js` | CTA organism |
+| `chatbot-test.spec.js` | Chatbot web component |
+| `comparison-chart.spec.js` | Comparison chart web component |
+| `consent-banner.spec.js` | Consent banner web component |
+| `container.spec.js` | Container organism |
+| `content-owner.spec.js` | Content owner organism |
+| `date-entry.spec.js` | Date entry organism |
+| `decision-tree.spec.js` | Decision tree web component |
+| `dynamic-contact-details.spec.js` | Dynamic contact details web component |
+| `empty.spec.js` | Empty page guard |
+| `external-search.spec.js` | External search organism |
+| `filtered-item.spec.js` | Filtered item organism |
+| `floating-button.spec.js` | Floating button web component |
+| `footer-item.spec.js` | Footer item organism |
+| `formstack-form.spec.js` | Formstack form web component |
+| `fuel-prices.spec.js` | Fuel prices web component |
+| `furniture-overview.spec.js` | Furniture overview web component |
+| `gauge-values.spec.js` | Gauge value web component |
+| `help-centre.spec.js` | Help centre web component |
+| `image-gallery.spec.js` | Image gallery organism |
+| `image-gen.spec.js` | Image generation web component |
+| `image-lazy-loading.spec.js` | Lazy loading behaviour |
+| `inspired-gallery.spec.js` | Inspired gallery web component |
+| `last-modified.spec.js` | Last modified organism |
+| `launch-container.spec.js` | Launch container web component |
+| `legal-footer.spec.js` | Legal footer organism |
+| `links.spec.js` | Links molecule |
+| `list-item.spec.js` | List item organism |
+| `lng-map.spec.js` | LNG map web component |
+| `metadata.spec.js` | Metadata organism |
+| `metas.spec.js` | Page meta tags |
+| `misc.spec.js` | Miscellaneous behaviours |
+| `mouseflow-analytics.spec.js` | Mouseflow analytics web component |
+| `msds-search.spec.js` | MSDS search web component |
+| `navigation.spec.js` | Navigation organism |
+| `notification.spec.js` | Notification organism |
+| `page.spec.js` | Page organism |
+| `page-header.spec.js` | Page header organism |
+| `page-header-banner.spec.js` | Page header banner organism |
+| `page-tags.spec.js` | Page tags organism |
+| `press-release.spec.js` | Press release organism |
+| `product-catalogue.spec.js` | Product catalogue web component |
+| `product-links.spec.js` | Product links web component |
+| `promo-banner.spec.js` | Promo banner organism |
+| `promo-bottom.spec.js` | Promo bottom organism |
+| `promo-card.spec.js` | Promo card organism |
+| `promo-full.spec.js` | Promo full organism |
+| `promo-image.spec.js` | Promo image organism |
+| `promo-lure.spec.js` | Promo lure organism |
+| `promo-simple.spec.js` | Promo simple organism |
+| `quote.spec.js` | Quote organism |
+| `redirect.spec.js` | Client-side redirect |
+| `rio-iframe.spec.js` | RIO iframe web component |
+| `rtl.spec.js` | Right-to-left layout |
+| `salsify-products.spec.js` | Salsify products web component |
+| `search.spec.js` | Search organism |
+| `search-nav.spec.js` | Search nav organism |
+| `section.spec.js` | Section layout |
+| `shout-out.spec.js` | Shout-out web component |
+| `simple-chart.spec.js` | Simple chart web component |
+| `simple-consent-api.spec.js` | Consent API |
+| `single-stat.spec.js` | Single stat web component |
+| `site-feedback.spec.js` | Site feedback web component |
+| `siteimprove.spec.js` | Siteimprove accessibility integration |
+| `skds-search.spec.js` | SKDS search web component |
+| `slider.spec.js` | Slider organism |
+| `smart-banner.spec.js` | Smart banner web component |
+| `standalone-asset.spec.js` | Standalone asset organism |
+| `standalone-table.spec.js` | Standalone table web component |
+| `state.spec.js` | Component state management |
+| `station-locator.spec.js` | Station locator web component |
+| `store-badges.spec.js` | Store badges web component |
+| `t.spec.js` | i18n translation helper |
+| `tabs.spec.js` | Tabs organism |
+| `themes.spec.js` | Theme switching |
+| `topbar.spec.js` | Topbar organism |
+| `topbar-button.spec.js` | Topbar button web component |
+| `web-component.spec.js` | Web component wrapper |
+| `zendesk-chat.spec.js` | Zendesk chat web component |
+
+</details>
+
+---
+
+## Code Coverage
+
+Coverage is collected via [Istanbul](https://istanbul.js.org/) instrumentation injected at build time, then reported after the Playwright test run.
+
+### Run tests with coverage
+
+```bash
+# Start the instrumented dev server
+npm start -- -i
+
+# In a second terminal, run tests (they collect coverage automatically)
+npm test
+```
+
+Or use the combined script:
+
+```bash
+npm run test:coverage
+```
+
+> `test:coverage` passes the `-i` flag to the build which instruments all JS files before Playwright tests run.
+
+### Coverage output
+
+Reports are written to `target/playwright/coverage/` after the test run completes.
+
+| Format | File | Use with |
+|---|---|---|
+| **LCOV** | `coverage/lcov.info` | VS Code Coverage Gutters, Codecov, Coveralls |
+| **Clover** | `coverage/clover.xml` | Jenkins, Bamboo |
+| **Cobertura** | `coverage/cobertura-coverage.xml` | Azure DevOps, GitLab CI |
+
+### Viewing coverage locally
+
+**VS Code** — install the [Coverage Gutters](https://marketplace.visualstudio.com/items?itemName=ryanluker.vscode-coverage-gutters) extension, then point it at `target/playwright/coverage/lcov.info`. Covered/uncovered lines appear in the editor gutter.
+
+**HTML report** — generate a human-readable HTML report with:
+
+```bash
+npx nyc report --reporter=html --temp-dir=target/playwright/coverage --report-dir=target/playwright/coverage/html
+```
+
+Then open `target/playwright/coverage/html/index.html` in a browser.
+
+**CI integration example (GitHub Actions):**
+
+```yaml
+- name: Run tests with coverage
+  run: |
+    npm start -- -i &
+    sleep 5
+    npm test
+
+- name: Upload coverage to Codecov
+  uses: codecov/codecov-action@v4
+  with:
+    files: target/playwright/coverage/lcov.info
+```
+
+### What is instrumented
+
+All JS files under `src/main/` and `src/wcs/` are instrumented. The following are excluded from coverage:
+
+- Third-party vendor bundles
+- Build tool scripts (`src/tools/`)
+- Test utility files (`src/test/utils/`)
+
+---
+
+## Build Scripts
+
+| Script | Command | Description |
+|---|---|---|
+| `start` | `npm start` | Build in watch/dev mode |
+| `build` | `npm run build` | Production build |
+| `test` | `npm test` | Run Playwright test suite |
+| `test:coverage` | `npm run test:coverage` | Run tests with Istanbul coverage |
+| `pack:check` | `npm run pack:check` | Dry-run pack (see included files) |
+| `pack:check:size` | `npm run pack:check:size` | Validate package stays under size limit |
+
+---
+
+## More Information
+
+### 💁 More information at the [Preact Website ➞](https://preactjs.com/)
+
+- [NPM (Preact)](https://www.npmjs.com/package/preact)
+- [Preact Chat](https://chat.preactjs.com/)
+- [Preact Backers](https://www.npmjs.com/package/preact?activeTab=readme#backers)
+- [Preact Sponsors](https://www.npmjs.com/package/preact?activeTab=readme#sponsors)
+- [Preact Coveralls](https://coveralls.io/github/preactjs/preact)
+- [Preact CDN (UNPKG)](https://unpkg.com/preact/dist/preact.min.js)
+
+### 📚 acinguiux-preact-components Links
+
+- [acinguiuxpreactdoc | Home](https://acinguiux-preact-components.vercel.app/acinguiuxpreactdoc.html)
+- [Home](https://acinguiux-preact-components.vercel.app/en_gb.html)
+
+---
+
+## License
+
+See [LICENSE](LICENSE) file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acinguiux-preact-components",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Sample extracted acinguiux-preact component library package",
   "type": "module",
   "main": "./src/main/export-main.js",
@@ -15,28 +15,29 @@
     "#acinguiux-preact/*.js": "./src/*.js"
   },
   "files": [
+    "README.md",
     "src/main",
     "src/wcs",
     "src/content/themes"
   ],
   "peerDependencies": {
-    "preact": "^10.28.2"
+    "preact": "^10.29.2"
   },
   "dependencies": {
     "chart.js": "^4.5.1",
     "exceljs": "^4.4.0",
-    "marked": "^16.1.2",
-    "nodemailer": "^8.0.7",
-    "preact": "^10.28.2",
-    "qr": "^0.5.4"
+    "marked": "^18.0.5",
+    "nodemailer": "^9.0.0",
+    "preact": "^10.29.2",
+    "qr": "^0.6.0"
   },
   "devDependencies": {
-    "@playwright/test": "^1.59.1",
+    "@playwright/test": "^1.60.0",
     "@siteimprove/alfa-playwright": "^0.82.1",
     "@siteimprove/alfa-test-utils": "^0.82.1",
     "convert-source-map": "^2.0.0",
     "dotenv": "^17.2.3",
-    "esbuild": "^0.27.2",
+    "esbuild": "^0.28.1",
     "istanbul-lib-coverage": "^3.2.2",
     "istanbul-lib-instrument": "^6.0.3",
     "istanbul-lib-report": "^3.0.1",
@@ -51,6 +52,7 @@
     "pack:check": "npm pack --dry-run",
     "pack:check:size": "node src/tools/check-pack-size.js",
     "pack:with-themes:check": "npm pack --dry-run --json --pack-destination .",
-    "test": "echo \"Add library test pipeline here\""
+    "test": "npx playwright test",
+    "test:coverage": "npx playwright test -- -i"
   }
 }