feat: widget enhancements — hidden mode, visibility toggles, i18n, S3 deployment (#3)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: jkrenge

.github/workflows/deploy_to_prod.yml

@@ -0,0 +1,61 @@
+name: Deploy to prod (release-tag)
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  push_to_s3:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.release.tag_name }}
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: |
+          npm run build
+          npm run build:site
+
+      - name: AWS - authentication
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          aws-region: eu-central-1
+          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
+
+      - name: Upload versioned files to S3
+        run: |
+          aws s3 cp ./dist s3://parcellab-cdn/apps/selection-guide-ui/v1/${{ github.event.release.tag_name }} \
+            --recursive \
+            --cache-control max-age=86400
+
+      - name: Upload latest plugin files to S3
+        run: |
+          aws s3 cp ./dist s3://parcellab-cdn/js/selection-guide-ui/v1 \
+            --recursive \
+            --cache-control max-age=86400
+
+      - name: Upload demo page to S3
+        run: |
+          aws s3 cp ./site s3://parcellab-cdn/apps/selection-guide-ui/v1/demo \
+            --recursive \
+            --cache-control max-age=86400
+
+      - name: Invalidate CloudFront cache
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id E3R5S2BJQI4RDS \
+            --paths "/js/selection-guide-ui/v1/*" "/apps/selection-guide-ui/v1/*"

.github/workflows/deploy_to_staging.yml

@@ -0,0 +1,52 @@
+name: Deploy to staging
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  NODE_VERSION: 22
+
+jobs:
+  push_to_s3:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: |
+          npm run build
+          npm run build:site
+
+      - name: AWS - authentication
+        uses: aws-actions/configure-aws-credentials@v6
+        with:
+          aws-region: eu-central-1
+          role-to-assume: ${{ secrets.AWS_ROLE_TO_ASSUME }}
+
+      - name: Upload to S3
+        run: |
+          aws s3 cp ./site s3://parcellab-cdn/playground/selection-guide-ui \
+            --recursive \
+            --cache-control max-age=86400
+
+      - name: Invalidate CloudFront cache
+        run: |
+          aws cloudfront create-invalidation \
+            --distribution-id E3R5S2BJQI4RDS \
+            --paths "/playground/selection-guide-ui/*"

.github/workflows/pages.yml

@@ -4,7 +4,7 @@ Open-source reference implementation of an embeddable size recommendation widget
 
 Use this widget as-is, or as a starting point for building your own custom integration against the API.
 
-**[Live demo](https://parcellab.github.io/selection-guide-ui/)**
+**[Live demo](https://cdn.parcellab.com/playground/selection-guide-ui/)**
 
 **Sample with short info text**
 
@@ -55,7 +55,7 @@ It ships as a zero-dependency bundle in two formats:
   data-not-found-mode="true-to-size"
 ></div>
 
-<script src="https://parcellab.github.io/selection-guide-ui/dist/size-recommender.iife.js" defer></script>
+<script src="https://cdn.parcellab.com/js/selection-guide-ui/v1/size-recommender.iife.js" defer></script>
 ```
 
 The IIFE build auto-initializes every `[data-size-recommender]` element on the page.
@@ -67,10 +67,15 @@ const widget = window.SizeRecommender.init({
   target: '#size-recommender',
   accountId: 1617954,
   productId: "Men's Iver Pants (tailored fit)",
+  locale: 'de',
   appearance: 'neutral',
   density: 'compact',
   surface: 'subtle',
   notFoundMode: 'true-to-size',
+  showPill: true,
+  showScale: true,
+  showRecommendation: true,
+  showSummary: true,
   className: 'merchant-fit-widget',
   theme: {
     backgroundColor: '#f6f6f6',
@@ -121,13 +126,17 @@ Full API documentation: [Size Recommender API Reference](https://product-api.par
 | `accountId` | `number \| string` | — | **Required**. parcelLab account identifier. |
 | `productId` | `string` | — | **Required**. Product identifier passed to the API. |
 | `articleName` | `string` | — | Legacy alias for `productId`. Still accepted for backwards compatibility. |
-| `locale` | `string` | `'en'` | Locale for default messages. |
+| `locale` | `string` | `'en'` | Language for default messages. Supported: `en`, `de`, `fr`, `it`, `es`. |
 | `messages` | `Partial<WidgetMessages>` | — | Override any default message string. |
-| `notFoundMode` | `'empty' \| 'true-to-size'` | `'empty'` | Behavior when the API returns 404 (see below). |
+| `notFoundMode` | `'empty' \| 'true-to-size' \| 'hidden'` | `'empty'` | Behavior when the API returns 404. `hidden` hides the widget entirely. |
 | `apiBaseUrl` | `string` | `'https://product-api.parcellab.com'` | Override the API base URL. |
 | `appearance` | `'neutral' \| 'colored'` | `'neutral'` | `neutral` is grayscale; `colored` uses gradient track. |
 | `density` | `'compact' \| 'comfortable'` | `'compact'` | `compact` suits PDP sidebars; `comfortable` adds more spacing. |
 | `surface` | `'subtle' \| 'plain'` | `'subtle'` | `subtle` renders a light card; `plain` renders inline. |
+| `showPill` | `boolean` | `true` | Show or hide the fit category pill badge. |
+| `showScale` | `boolean` | `true` | Show or hide the fit position scale bar. |
+| `showRecommendation` | `boolean` | `true` | Show or hide the entire recommendation box. |
+| `showSummary` | `boolean` | `true` | Show or hide the LLM summary within the recommendation. |
 | `className` | `string` | — | Extra CSS classes added to the root element. |
 | `theme` | `Partial<WidgetTheme>` | — | CSS token overrides (colors, radius, etc.). |
 
@@ -144,7 +153,11 @@ When using the IIFE auto-init, configure via `data-*` attributes:
   data-appearance="colored"
   data-density="comfortable"
   data-surface="plain"
-  data-locale="en"
+  data-locale="de"
+  data-show-pill="true"
+  data-show-scale="true"
+  data-show-recommendation="true"
+  data-show-summary="false"
   data-messages='{"title":"How It Fits"}'
   data-theme='{"backgroundColor":"#f6f6f6","radius":"12px"}'
   data-class-name="my-custom-class"
@@ -153,10 +166,11 @@ When using the IIFE auto-init, configure via `data-*` attributes:
 
 ## 404 Handling
 
-When a product has no recommendation data, the widget supports two modes:
+When a product has no recommendation data, the widget supports three modes:
 
 - **`empty`** (default) — shows a "no data available" message
 - **`true-to-size`** — renders a "likely true to size" fallback without confidence or summary
+- **`hidden`** — hides the widget entirely (`display: none`); the widget reappears when valid data is provided via `update()` or `refresh()`
 
 ## Styling
 
@@ -169,7 +183,7 @@ The widget renders in **light DOM** (not Shadow DOM), so host-page typography in
 .pl-size-recommender--{neutral|colored}
 .pl-size-recommender--density-{compact|comfortable}
 .pl-size-recommender--surface-{subtle|plain}
-.pl-size-recommender--state-{loading|ready|fallback-true|empty|error}
+.pl-size-recommender--state-{loading|ready|fallback-true|empty|error|hidden}
 .pl-size-recommender--fit-{small|true|large|unknown}
 ```
 
@@ -266,15 +280,19 @@ npm test
 
 Runs the Vitest test suite with jsdom.
 
-### GitHub Pages
+### Deployment
 
-```sh
-npm run build:pages
-```
+The project deploys to S3/CloudFront via GitHub Actions:
+
+- **Staging:** automatically deployed on push to `main` to `s3://parcellab-cdn/playground/selection-guide-ui/`
+- **Production:** deployed on GitHub release to `s3://parcellab-cdn/js/selection-guide-ui/v1/` (latest) and `s3://parcellab-cdn/apps/selection-guide-ui/v1/{tag}/` (versioned)
 
-Builds a static demo site to `site/`. The repository is configured to deploy this automatically via GitHub Actions on push to `main`.
+Build the demo site locally:
 
-**Demo URL:** [https://parcellab.github.io/selection-guide-ui/](https://parcellab.github.io/selection-guide-ui/)
+```sh
+npm run build
+npm run build:site
+```
 
 ## Building Your Own
 

README.md

@@ -112,6 +112,21 @@ <h2 class="text-base font-semibold">Configuration</h2>
               />
             </label>
 
+            <label class="grid gap-1.5 text-sm font-semibold text-navy-500">
+              Language
+              <select
+                id="locale"
+                name="locale"
+                class="field bg-white border border-navy-200 rounded-lg h-11 px-3 text-navy-800 font-normal text-sm"
+              >
+                <option value="en">English</option>
+                <option value="de">Deutsch</option>
+                <option value="fr">Francais</option>
+                <option value="it">Italiano</option>
+                <option value="es">Espanol</option>
+              </select>
+            </label>
+
             <label class="grid gap-1.5 text-sm font-semibold text-navy-500">
               Missing product
               <select
@@ -121,6 +136,7 @@ <h2 class="text-base font-semibold">Configuration</h2>
               >
                 <option value="true-to-size">Show "likely true to size" fallback</option>
                 <option value="empty">Show empty state</option>
+                <option value="hidden">Hide widget entirely</option>
               </select>
             </label>
 
@@ -132,7 +148,7 @@ <h2 class="text-base font-semibold">Configuration</h2>
                 class="field bg-white border border-navy-200 rounded-lg h-11 px-3 text-navy-800 font-normal text-sm"
               >
                 <option value="neutral">Neutral</option>
-                <option value="colored">Colored</option>
+                <option value="colored" selected>Colored</option>
                 <option value="alert">Alert</option>
               </select>
             </label>
@@ -145,7 +161,7 @@ <h2 class="text-base font-semibold">Configuration</h2>
                 class="field bg-white border border-navy-200 rounded-lg h-11 px-3 text-navy-800 font-normal text-sm"
               >
                 <option value="compact">Compact</option>
-                <option value="comfortable">Comfortable</option>
+                <option value="comfortable" selected>Comfortable</option>
               </select>
             </label>
 
@@ -157,9 +173,29 @@ <h2 class="text-base font-semibold">Configuration</h2>
                 class="field bg-white border border-navy-200 rounded-lg h-11 px-3 text-navy-800 font-normal text-sm"
               >
                 <option value="subtle">Subtle card</option>
-                <option value="plain">Plain inline</option>
+                <option value="plain" selected>Plain inline</option>
               </select>
             </label>
+
+            <fieldset class="space-y-2">
+              <legend class="text-xs font-semibold text-navy-500 uppercase tracking-wide">Visibility</legend>
+              <label class="flex items-center gap-2 text-sm text-navy-700 cursor-pointer">
+                <input type="checkbox" id="show-pill" checked class="accent-navy-800" />
+                Show size tag
+              </label>
+              <label class="flex items-center gap-2 text-sm text-navy-700 cursor-pointer">
+                <input type="checkbox" id="show-scale" checked class="accent-navy-800" />
+                Show scale
+              </label>
+              <label class="flex items-center gap-2 text-sm text-navy-700 cursor-pointer">
+                <input type="checkbox" id="show-recommendation" checked class="accent-navy-800" />
+                Show recommendation
+              </label>
+              <label class="flex items-center gap-2 text-sm text-navy-700 cursor-pointer">
+                <input type="checkbox" id="show-summary" checked class="accent-navy-800" />
+                Show summary
+              </label>
+            </fieldset>
           </div>
 
           <div class="flex flex-wrap gap-3 pt-2">