FormBuilder

import { createFormBuilder } from '@blukavantui/web/form-builder';
import { createFormRenderer, type BluFormDefinition, type FormValues, type BluFormAttachment } from '@blukavantui/web/form-renderer';
import '@blukavantui/web/form-builder.css';
import '@blukavantui/web/form-renderer.css';

// Load @blukavantui/web/theme.css once in your application's browser entry.
// These interfaces belong to this application example, not to the component SDK.
export interface SavedForm {
  FormId: string;
  RawJson: string;       // JSON.stringify(complete BluFormDefinition)
  ValuesJson: string;    // JSON.stringify(complete submitted FormValues)
  Revision: number;      // server-issued definition revision
  ResponseRevision: number; // server-issued response revision (prevents lost edits)
  Upload: { url: string; headers: Record<string, string>; withCredentials?: boolean };
}
export interface FormStore {
  load(formId: string, signal: AbortSignal): Promise<SavedForm>;
  saveDefinition(formId: string, rawJson: string, expectedRevision: number, signal: AbortSignal): Promise<{ Revision: number }>;
  saveResponse(formId: string, valuesJson: string, definitionRevision: number, expectedResponseRevision: number, signal: AbortSignal): Promise<{ ResponseRevision: number }>;
  download(fileId: string, signal: AbortSignal): Promise<Blob>;
}
export interface WorkspaceOptions {
  formIds: string[];
  store: FormStore;
  mode?: 'design' | 'fill';
}

/** One mounted workspace loads any authorized FormId. No DOM tree per form. */
export function mountFormWorkspace(host: HTMLElement, options: WorkspaceOptions) {
  const lifetime = new AbortController(), store = options.store;
  const panel = document.createElement('section'), controls = document.createElement('div');
  controls.style.cssText = 'display:flex;flex-wrap:wrap;gap:12px;align-items:center;margin-bottom:16px';
  const select = document.createElement('select'); select.setAttribute('aria-label', 'Form to load');
  for (const id of options.formIds) { const option = document.createElement('option'); option.value = id; option.textContent = id; select.append(option); }
  const reload = document.createElement('button'); reload.type = 'button'; reload.textContent = 'Reload saved form (discard draft)';
  const design = document.createElement('button'); design.type = 'button'; design.textContent = 'Design form';
  const fill = document.createElement('button'); fill.type = 'button'; fill.textContent = 'Fill saved form';
  for (const button of [reload, design, fill]) button.className = 'blu-forms__button';
  const status = document.createElement('p'); status.setAttribute('role', 'status');
  const surface = document.createElement('div'), downloads = document.createElement('div');
  controls.append(select, reload, design, fill); panel.append(controls, status, surface, downloads); host.append(panel);
  let record: SavedForm | undefined, activeId = options.formIds[0] || '', mode = options.mode || 'fill';
  let builder: ReturnType<typeof createFormBuilder> | undefined, renderer: ReturnType<typeof createFormRenderer> | undefined;
  let busy = false, generation = 0, reset = 0, disposed = false;
  const current = (ticket: number) => !disposed && ticket === generation;
  function message(error: unknown) { return error instanceof Error ? error.message : 'The operation failed. Please retry.'; }
  function setBusy(value: boolean) {
    busy = value;
    for (const input of [select, reload, design, fill]) input.disabled = value;
    builder?.update({ IsDisabled: value }); renderer?.update({ IsDisabled: value });
  }
  function fileLinks(definition: BluFormDefinition, values: FormValues) {
    downloads.replaceChildren();
    const fields = definition.Pages.flatMap(page => page.Sections.flatMap(section => section.Fields)).filter(field => field.Type === 'FileUpload');
    for (const field of fields) {
      const files = values[field.Key]; if (!Array.isArray(files)) continue;
      for (const file of files as BluFormAttachment[]) {
        if (!file || typeof file.Id !== 'string') continue;
        const button = document.createElement('button'); button.type = 'button'; button.className = 'blu-forms__button';
        button.textContent = 'Download ' + file.Name; button.style.margin = '8px';
        button.onclick = async () => {
          button.disabled = true; const ticket = generation;
          try {
            const blob = await store.download(file.Id, lifetime.signal); if (!current(ticket)) return;
            const url = URL.createObjectURL(blob), anchor = document.createElement('a');
            anchor.href = url; anchor.download = file.Name; anchor.hidden = true; panel.append(anchor); anchor.click(); anchor.remove();
            setTimeout(() => URL.revokeObjectURL(url), 1000);
          } catch (error) { if (current(ticket)) status.textContent = message(error); }
          finally { button.disabled = false; }
        };
        downloads.append(button);
      }
    }
  }
  async function load(formId: string) {
    if (busy || disposed) return;
    let ticket = generation; setBusy(true); status.textContent = 'Loading saved form…';
    try {
      const loaded = await store.load(formId, lifetime.signal); if (!current(ticket)) return;
      if (loaded.FormId !== formId) throw Error('The server returned a different form.');
      const definition = JSON.parse(loaded.RawJson) as BluFormDefinition, values = JSON.parse(loaded.ValuesJson) as FormValues;
      if (definition.Version !== 1 || !Array.isArray(definition.Pages) || !values || Array.isArray(values) || typeof values !== 'object') throw Error('Invalid saved form JSON.');
      record = loaded; activeId = formId; select.value = formId;
      ticket = ++generation;
      // Replace the instances only on an explicit load/mode change, never on each keystroke.
      builder?.destroy(); renderer?.destroy(); builder = undefined; renderer = undefined;
      surface.replaceChildren(); downloads.replaceChildren();
      const resetKey = String(++reset);
      if (mode === 'design') {
        builder = createFormBuilder(surface, { FormId: formId, Definition: definition, ResetKey: resetKey }, {
          async SaveRequested(requestId, requestedFormId, requestedDefinition) {
            if (busy || requestedFormId !== activeId || !current(ticket)) return;
            setBusy(true);
            try {
              const result = await store.saveDefinition(requestedFormId, JSON.stringify(requestedDefinition), loaded.Revision, lifetime.signal);
              if (!current(ticket)) return;
              loaded.Revision = result.Revision; loaded.RawJson = JSON.stringify(requestedDefinition);
              builder!.update({ SaveResultRequestId: requestId, SaveResultSuccess: true, SaveResultMessage: 'Form saved. Choose Fill saved form to use it.' });
              status.textContent = 'Complete definition saved as RawJson.';
            } catch (error) {
              if (current(ticket)) { builder!.update({ SaveResultRequestId: requestId, SaveResultSuccess: false, SaveResultMessage: message(error) }); status.textContent = message(error); }
            } finally { if (current(ticket)) setBusy(false); }
          },
          Error: text => { status.textContent = text; },
        });
      } else {
        renderer = createFormRenderer(surface, { FormId: formId, Definition: definition, Values: values, ResetKey: resetKey,
          UploadUrl: loaded.Upload.url, UploadHeaders: loaded.Upload.headers, UploadWithCredentials: loaded.Upload.withCredentials || false }, {
          ValuesChanged: draft => { fileLinks(definition, draft); }, // Draft state only; uploads yield durable IDs here.
          async SubmitRequested(requestId, requestedFormId, submittedValues) {
            if (busy || requestedFormId !== activeId || !current(ticket)) return;
            setBusy(true);
            try {
              const result = await store.saveResponse(requestedFormId, JSON.stringify(submittedValues), loaded.Revision, loaded.ResponseRevision, lifetime.signal);
              if (!current(ticket)) return;
              loaded.ResponseRevision = result.ResponseRevision; loaded.ValuesJson = JSON.stringify(submittedValues);
              renderer!.update({ SubmitResultRequestId: requestId, SubmitResultSuccess: true, SubmitResultMessage: 'Answers and attachment references saved.' });
              fileLinks(definition, submittedValues); status.textContent = 'Saved. Reload to restore the form, answers and attachments.';
            } catch (error) {
              if (current(ticket)) { renderer!.update({ SubmitResultRequestId: requestId, SubmitResultSuccess: false, SubmitResultMessage: message(error) }); status.textContent = message(error); }
            } finally { if (current(ticket)) setBusy(false); }
          },
          Error: text => { status.textContent = text; },
        });
        fileLinks(definition, values);
      }
      design.setAttribute('aria-pressed', String(mode === 'design')); fill.setAttribute('aria-pressed', String(mode === 'fill'));
      status.textContent = 'Loaded saved definition and answers. Files are downloaded through your application.';
    } catch (error) { if (current(ticket)) { select.value = activeId; status.textContent = message(error); } }
    finally { if (current(ticket)) setBusy(false); }
  }
  select.onchange = () => { void load(select.value); };
  reload.onclick = () => { void load(activeId); };
  design.onclick = () => { if (!busy) { mode = 'design'; void load(activeId); } };
  fill.onclick = () => { if (!busy) { mode = 'fill'; void load(activeId); } };
  void load(activeId);
  return { reload() { return load(activeId); }, get record() { return record; }, destroy() { disposed = true; generation++; lifetime.abort(); builder?.destroy(); renderer?.destroy(); panel.remove(); } };
}

import type { FormStore, SavedForm } from './form-workspace';

/** Connect the workspace to same-origin application routes documented in the guide.
 * Implement these routes on YOUR server; they are not included in the SDK.
 * The server derives the owner from its session, validates the stored definition,
 * checks attachment ownership, and uses optimistic concurrency for both records.
 */
export function createHttpFormStore(baseUrl: string, headers: () => Record<string, string>): FormStore {
  const base = baseUrl.replace(/\/$/, '');
  async function request<T>(path: string, signal: AbortSignal, body?: unknown): Promise<T> {
    const response = await fetch(base + path, { method: body === undefined ? 'GET' : 'PUT', signal,
      credentials: 'same-origin', cache: 'no-store',
      headers: { Accept: 'application/json', ...headers(), ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
    });
    const result = await response.json().catch(() => null);
    if (!response.ok) throw Error(result?.error || 'Request failed (' + response.status + '). Your draft is retained.');
    if (!result) throw Error('The server returned an invalid JSON response.');
    return result as T;
  }
  return {
    load: (formId, signal) => request<SavedForm>('/' + encodeURIComponent(formId), signal),
    saveDefinition: (formId, RawJson, ExpectedRevision, signal) => request('/' + encodeURIComponent(formId) + '/definition', signal, { RawJson, ExpectedRevision }),
    saveResponse: (formId, ValuesJson, DefinitionRevision, ExpectedResponseRevision, signal) => request('/' + encodeURIComponent(formId) + '/response', signal, { ValuesJson, DefinitionRevision, ExpectedResponseRevision }),
    async download(fileId, signal) {
      const response = await fetch(base + '/attachments/' + encodeURIComponent(fileId), { signal, credentials: 'same-origin', cache: 'no-store', headers: headers() });
      if (!response.ok) throw Error(response.status === 404 ? 'Attachment expired or unavailable. Remove it and upload it again.' : 'Download failed. Please retry.');
      return response.blob();
    },
  };
}

import { validateFormValues, type BluFormDefinition, type FormValues } from '@blukavantui/web/form-renderer';
import type { FormStore } from './form-workspace';

// WEBSITE DEMONSTRATION ONLY. Your own app uses createHttpFormStore and its own
// endpoints. /demo/forms/files is private to this site's session and is not a
// public upload service. Definitions/answers below are browser-local, NOT a DB.
const definition: BluFormDefinition = { Version: 1, Key: 'web_storage_example', Title: 'Save a form with attachments',
  Description: 'Upload a test file, submit, reload this page and download it. Demo uploads expire after two hours.',
  SubmitLabel: 'Save response & attachments', Pages: [{ Key: 'request', Title: 'Your request', Sections: [{ Key: 'details', Fields: [
    { Key: 'notes', Type: 'TextArea', Label: 'Notes', MaxLength: 500 },
    { Key: 'files', Type: 'FileUpload', Label: 'Supporting files', Required: true, Accept: '.txt,.pdf,.png,.jpg,.jpeg', MaxFiles: 3, MaxFileSizeMB: 1 },
  ] }] }] };
type BrowserRecord = { RawJson: string; ValuesJson: string; Revision: number; ResponseRevision: number };
export function createWebsiteDemoStore(scenario: string): FormStore {
  const key = (id: string) => 'blukavantui-code-storage-v1:' + scenario + ':' + id;
  const read = (id: string): BrowserRecord => JSON.parse(localStorage.getItem(key(id)) || 'null') || { RawJson: JSON.stringify(definition), ValuesJson: '{}', Revision: 1, ResponseRevision: 0 };
  const save = (id: string, record: BrowserRecord) => localStorage.setItem(key(id), JSON.stringify(record));
  async function files(signal: AbortSignal) {
    const response = await fetch('/demo/forms/files', { signal, credentials: 'same-origin', cache: 'no-store' });
    if (!response.ok) throw Error('Could not connect attachment storage. Reload and retry.');
    return (await response.json()).files as { Id: string; formId: string; fieldKey: string; ExpiresAt: number }[];
  }
  return {
    async load(FormId, signal) {
      await files(signal);
      return { FormId, ...read(FormId), Upload: { url: '/demo/forms/files', headers: { 'x-csrf-token': document.querySelector<HTMLMetaElement>('meta[name=csrf-token]')?.content || '' } } };
    },
    async saveDefinition(id, RawJson, expectedRevision) {
      const old = read(id); if (old.Revision !== expectedRevision) throw Error('This definition changed in another tab. Reload before saving.');
      JSON.parse(RawJson);
      const next = { RawJson, Revision: old.Revision + 1, ValuesJson: '{}', ResponseRevision: old.ResponseRevision + 1 };
      save(id, next); return { Revision: next.Revision };
    },
    async saveResponse(id, ValuesJson, definitionRevision, expectedResponseRevision, signal) {
      const storedFiles = await files(signal), old = read(id), form: BluFormDefinition = JSON.parse(old.RawJson), values: FormValues = JSON.parse(ValuesJson);
      if (old.Revision !== definitionRevision || old.ResponseRevision !== expectedResponseRevision) throw Error('This record changed in another tab. Reload before submitting.');
      const errors = validateFormValues(form, values); if (errors.length) throw Error(errors[0].Message);
      for (const field of form.Pages.flatMap(page => page.Sections.flatMap(section => section.Fields)).filter(field => field.Type === 'FileUpload')) {
        const references = values[field.Key]; if (!Array.isArray(references)) continue;
        for (const file of references) if (typeof file !== 'object' || !storedFiles.some(stored => stored.Id === file.Id && stored.formId === id && stored.fieldKey === field.Key && stored.ExpiresAt > Date.now())) throw Error('An attachment expired. Remove it and upload it again.');
      }
      save(id, { ...old, ValuesJson, ResponseRevision: old.ResponseRevision + 1 }); return { ResponseRevision: old.ResponseRevision + 1 };
    },
    async download(id, signal) {
      const response = await fetch('/demo/forms/files/' + encodeURIComponent(id), { signal, credentials: 'same-origin', cache: 'no-store' });
      if (!response.ok) throw Error('This attachment expired or is unavailable in this browser session.');
      return response.blob();
    },
  };
}

Authenticated session; optional CSRF/auth headers

{
  "FormId": "service_request",
  "RawJson": "JSON.stringify(completeDefinition)",
  "ValuesJson": "JSON.stringify(savedAnswers)",
  "Revision": 1,
  "ResponseRevision": 0,
  "Upload": {
    "url": "/api/forms/attachments",
    "headers": {
      "x-csrf-token": "fresh session CSRF token"
    },
    "withCredentials": false
  }
}

{
  "RawJson": "complete definition JSON string",
  "ExpectedRevision": 1
}

{
  "Revision": 2
}

{
  "ValuesJson": "complete answer JSON string",
  "DefinitionRevision": 2,
  "ExpectedResponseRevision": 0
}

{
  "ResponseRevision": 1
}

multipart/form-data: file (binary), formId (text), fieldKey (text), clientKey (text). Browser sets Content-Type and boundary.

{
  "Id": "durable opaque storage ID",
  "stored": true
}

Authenticated session and required auth headers

Stored file bytes; Content-Disposition: attachment; Cache-Control: private, no-store; X-Content-Type-Options: nosniff