@shift-software/survey-web-component 0.0.0-stage → 0.1.0

package/dist/library-fonts.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=library-fonts.d.ts.map

package/dist/library-fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"library-fonts.d.ts","sourceRoot":"","sources":["../src/library-fonts.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@shift-software/survey-web-component",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Custom-element wrapper around @shift-software/survey-renderer. Exposes <shift-survey> so non-React hosts (Blazor live-preview, plain HTML embeds, Stencil apps) can mount a survey without pulling React into the host. Ships React + renderer inside the bundle.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ShiftSoftware/ADP",
+    "directory": "ADP.Surveys/renderer/packages/survey-web-component"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test.watch": "vitest"
+  },
+  "dependencies": {
+    "@shift-software/survey-renderer": "^0.1.0",
+    "@shift-software/survey-sdk": "^0.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.6.3",
+    "vite": "^6.0.3",
+    "vitest": "^2.1.8"
+  }
+}

package/src/ShiftSurveyElement.tsx

@@ -0,0 +1,273 @@
+import { createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { SurveyRenderer } from '@shift-software/survey-renderer';
+// Relative path on purpose — the renderer's `exports` map is strict and doesn't
+// whitelist `?inline`; reaching through the workspace path is the most robust
+// way to inline the stylesheet at build time.
+import rendererStyles from '../../survey-renderer/src/styles.css?inline';
+import {
+  SurveyClient,
+  type Survey,
+  type SurveySubmission,
+} from '@shift-software/survey-sdk';
+
+/**
+ * `<shift-survey>` — custom-element wrapper around `<SurveyRenderer>`.
+ *
+ * Two usage modes, pick whichever fits the host:
+ *
+ *   1. **API mode** (attribute-driven): the element fetches schema + submits
+ *      responses against the Surveys API on its own.
+ *      ```html
+ *      <shift-survey
+ *        instance-id="abc-123-guid"
+ *        api-base="https://api.example.com/api/Surveys"
+ *        locale="ar"></shift-survey>
+ *      ```
+ *
+ *   2. **Schema mode** (property-driven): the host provides the schema + onSubmit
+ *      directly as DOM properties. Used by the Blazor builder's live-preview
+ *      (Phase 4) — the host pushes draft schemas via JS interop as the author
+ *      types.
+ *      ```ts
+ *      const el = document.querySelector('shift-survey');
+ *      el.schema = draftSchema;
+ *      el.onSubmit = (submission) => { ... };
+ *      ```
+ *
+ * Lifecycle events bubble up as CustomEvents on the element (`survey:loaded`,
+ * `survey:screen-changed`, `survey:completed`, `survey:error`) — same vocabulary
+ * as the postMessage protocol, but dispatched as DOM events for page-level hosts.
+ * If the element also sits inside an iframe, postMessage emission still fires
+ * for the iframe parent; the two channels coexist.
+ */
+export class ShiftSurveyElement extends HTMLElement {
+  static get observedAttributes(): string[] {
+    return ['instance-id', 'api-base', 'locale', 'mode', 'active-screen-id', 'locale-picker'];
+  }
+
+  /** Schema-mode setter. Assigning this swaps the element into schema mode and
+   *  re-renders with the new schema immediately. */
+  #schema: Survey | null = null;
+  /** Schema-mode submit handler. In API mode the element manages this itself. */
+  #onSubmit: ((submission: SurveySubmission) => void | Promise<void>) | null = null;
+
+  #root: Root | null = null;
+  #mount: HTMLDivElement | null = null;
+  #apiSchema: Survey | null = null;
+  #apiError: Error | null = null;
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+
+  // ─── Lifecycle ───────────────────────────────────────────────────────────
+
+  connectedCallback(): void {
+    if (!this.shadowRoot) return;
+    // Inject the renderer's stylesheet once. Shadow DOM blocks the host page's
+    // CSS from leaking in — we own our visual layer end-to-end.
+    if (!this.shadowRoot.querySelector('style[data-shift-survey]')) {
+      const style = document.createElement('style');
+      style.setAttribute('data-shift-survey', '');
+      style.textContent = rendererStyles;
+      this.shadowRoot.appendChild(style);
+    }
+    if (!this.#mount) {
+      this.#mount = document.createElement('div');
+      this.#mount.className = 'shift-survey-mount';
+      this.shadowRoot.appendChild(this.#mount);
+    }
+    if (!this.#root) this.#root = createRoot(this.#mount);
+    this.#renderIfReady();
+    this.#maybeFetchSchema();
+  }
+
+  disconnectedCallback(): void {
+    // Defer the unmount — disconnectedCallback fires synchronously during DOM
+    // moves, and React 19 complains if we tear down a root mid-render. A
+    // microtask delay plus a re-check gives React room to settle. Guard against
+    // test teardown races where `window` has been torn down by jsdom.
+    queueMicrotask(() => {
+      if (this.isConnected || typeof window === 'undefined') return;
+      try {
+        this.#root?.unmount();
+      } catch {
+        // jsdom tears down mid-unmount during test runs — no-op is safe.
+      }
+      this.#root = null;
+    });
+  }
+
+  attributeChangedCallback(name: string, oldVal: string | null, newVal: string | null): void {
+    if (oldVal === newVal) return;
+    if (name === 'instance-id' || name === 'api-base') {
+      // API-mode inputs changed — drop any cached schema and refetch.
+      this.#apiSchema = null;
+      this.#apiError = null;
+      this.#maybeFetchSchema();
+    }
+    this.#renderIfReady();
+  }
+
+  // ─── Properties ──────────────────────────────────────────────────────────
+
+  get schema(): Survey | null {
+    return this.#schema;
+  }
+  set schema(value: Survey | null) {
+    this.#schema = value;
+    this.#renderIfReady();
+  }
+
+  get onSubmit(): ((submission: SurveySubmission) => void | Promise<void>) | null {
+    return this.#onSubmit;
+  }
+  set onSubmit(value: ((submission: SurveySubmission) => void | Promise<void>) | null) {
+    this.#onSubmit = value;
+    this.#renderIfReady();
+  }
+
+  /** Builder-preview jump target. Assigning a screen id makes the renderer
+   *  jump to that screen (answers preserved); the user can navigate freely
+   *  afterwards. Mirrors the `active-screen-id` attribute; the property wins
+   *  when both are set. */
+  #activeScreenId: string | null = null;
+  get activeScreenId(): string | null {
+    return this.#activeScreenId ?? this.getAttribute('active-screen-id');
+  }
+  set activeScreenId(value: string | null) {
+    this.#activeScreenId = value;
+    this.#renderIfReady();
+  }
+
+  /** Bump to re-issue a jump to the screen already set on {@link activeScreenId}.
+   *  Property-only (no attribute) — it is a transient signal, not page state. */
+  #activeScreenJumpToken = 0;
+  get activeScreenJumpToken(): number {
+    return this.#activeScreenJumpToken;
+  }
+  set activeScreenJumpToken(value: number) {
+    this.#activeScreenJumpToken = value;
+    this.#renderIfReady();
+  }
+
+  // ─── Internals ───────────────────────────────────────────────────────────
+
+  #maybeFetchSchema(): void {
+    // Only fetch if we're in API mode (instance-id set) AND not already served
+    // via the schema property.
+    if (this.#schema) return;
+    const instanceId = this.getAttribute('instance-id');
+    if (!instanceId) return;
+    const apiBase = this.getAttribute('api-base');
+    if (!apiBase) return;
+    const client = new SurveyClient({ baseUrl: apiBase });
+    client
+      .fetchSchema(instanceId)
+      .then((schema) => {
+        this.#apiSchema = schema;
+        this.#renderIfReady();
+      })
+      .catch((error: Error) => {
+        this.#apiError = error;
+        this.#dispatch('survey:error', { message: error.message });
+        this.#renderIfReady();
+      });
+  }
+
+  #renderIfReady(): void {
+    if (!this.#root) return;
+
+    const apiBase = this.getAttribute('api-base');
+    const instanceId = this.getAttribute('instance-id');
+    const locale = this.getAttribute('locale') ?? undefined;
+    const agentMode = this.getAttribute('mode') === 'agent';
+    // `locale-picker` is an override, not a switch: absent means "let the renderer
+    // decide" (shown when the survey declares more than one locale), so an existing
+    // host that sets nothing gets the picker without changing its markup.
+    const localePickerAttr = this.getAttribute('locale-picker');
+    const showLocalePicker =
+      localePickerAttr === null
+        ? undefined
+        : localePickerAttr !== 'false' && localePickerAttr !== 'off';
+
+    // Prefer the explicit schema property (schema mode) over a fetched one.
+    const schema = this.#schema ?? this.#apiSchema;
+
+    if (this.#apiError && !schema) {
+      this.#root.render(
+        createElement(
+          'div',
+          { className: 'shift-survey-error', role: 'alert' },
+          this.#apiError.message,
+        ),
+      );
+      return;
+    }
+    if (!schema) {
+      this.#root.render(
+        createElement('div', { className: 'shift-survey-loading' }, 'Loading…'),
+      );
+      return;
+    }
+
+    // Wire onSubmit. Schema mode uses the property the host set; API mode hits
+    // the public submit endpoint via SurveyClient.
+    const onSubmit = this.#schema
+      ? (this.#onSubmit ??
+        ((submission: SurveySubmission) => {
+          this.#dispatch('survey:completed', { ...submission });
+        }))
+      : async (submission: SurveySubmission) => {
+          if (!apiBase || !instanceId)
+            throw new Error('shift-survey: API mode requires both instance-id and api-base attributes.');
+          const client = new SurveyClient({ baseUrl: apiBase });
+          await client.submitResponse(instanceId, submission);
+        };
+
+    const activeScreenId = this.activeScreenId;
+
+    this.#root.render(
+      createElement(SurveyRenderer, {
+        schema,
+        onSubmit,
+        ...(locale ? { locale } : {}),
+        ...(showLocalePicker === undefined ? {} : { showLocalePicker }),
+        // Mirror the respondent's pick back onto the element so a host can read it
+        // (and so the attribute stays an accurate description of what is showing).
+        onLocaleChange: (next: string) => {
+          if (this.getAttribute('locale') !== next) this.setAttribute('locale', next);
+          this.#dispatch('survey:locale-changed', { locale: next });
+        },
+        ...(activeScreenId
+          ? { activeScreenId, activeScreenJumpToken: this.#activeScreenJumpToken }
+          : {}),
+        // Let the element be the resume key in API mode so two surveys on the
+        // same host page don't clobber each other.
+        ...(instanceId ? { resumeKey: instanceId } : {}),
+        ...(agentMode ? { submissionMeta: { mode: 'agent' } } : {}),
+        // CustomEvents are the web-component's channel; postMessage stays opt-in
+        // via iframe auto-detect on the enclosing page (unchanged).
+        onScreenChange: (screenId: string | null) =>
+          this.#dispatch('survey:screen-changed', { screenId }),
+        onCompleted: (screenId: string | null) =>
+          this.#dispatch('survey:completed', { screenId }),
+      }),
+    );
+
+    if (!this.#loadedDispatched) {
+      this.#loadedDispatched = true;
+      this.#dispatch('survey:loaded', {});
+    }
+  }
+
+  #loadedDispatched = false;
+
+  #dispatch(type: string, detail: Record<string, unknown>): void {
+    this.dispatchEvent(
+      new CustomEvent(type, { detail, bubbles: true, composed: true }),
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+import './library-fonts.js'; // first: see the file
+import { ShiftSurveyElement } from './ShiftSurveyElement.js';
+
+export { ShiftSurveyElement };
+
+/** Register the `<shift-survey>` custom element. Idempotent — calling twice on
+ *  the same page is a no-op. Consumers who want a different tag name can import
+ *  `ShiftSurveyElement` directly and call `customElements.define(...)` with it. */
+export function registerShiftSurvey(tagName = 'shift-survey'): void {
+  if (typeof window === 'undefined' || typeof customElements === 'undefined') return;
+  if (customElements.get(tagName)) return;
+  customElements.define(tagName, ShiftSurveyElement);
+}
+
+// Auto-register on import so plain `<script type="module" src="...">` embeds
+// Just Work™. Callers who want to rename the tag should import the class and
+// register themselves BEFORE loading this module, or set the tag name before
+// import. This default covers the 90% case.
+registerShiftSurvey();

package/src/library-fonts.ts

@@ -0,0 +1,7 @@
+/**
+ * The booking question's calendar comes from adp-web-components, whose global script adds a
+ * Google Fonts stylesheet to the page when it first loads. The survey sets its own font on the
+ * calendar, so it opts out. This must be the entry's first import: imports run in order, before
+ * any module body, and the library reads the flag as it loads.
+ */
+if (typeof window !== 'undefined') (window as { adpWebComponentsFonts?: boolean }).adpWebComponentsFonts ??= false;

package/src/styles.d.ts

@@ -0,0 +1,6 @@
+/** Vite's `?inline` query returns CSS as a string at build time. Declare the
+ *  module shape so TS resolves the import. */
+declare module '*.css?inline' {
+  const content: string;
+  export default content;
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.