@seamlet/astro 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.4.0
+
+- Documents: `file({ label })` holds a PDF the owner uploads in the CMS, `{ src, name }` (`FileValue`): a price list, a menu, a contract. An empty name of a file asks for its file (`missing-file-src`). A static build copies the uploaded documents its pages link to, as it copies the photos, and the route of uploads serves them on request; `isUploadedFile` names both.
+
+A site with a file field needs a CMS that reads 1.4 (cms.seamlet.ru from its release that takes documents). Code with an exhaustive `switch` over `FieldKind` or over the issues of `parseContent` gets the new member to handle.
+
+## 1.3.0
+
+- Requests: `requestForm({ id, title, fields })` with `requestText`, `requestLongText`, `requestPhone`, `requestEmail` and `requestChoice` declares a form visitors send the business requests with; `defineSeamletSite` takes them as `forms`, and the site's description tells the CMS about them. `RequestForm.astro` renders one, with a checkbox of consent of its own; it is posted to the CMS without a script, and sent in place with it.
+- `readRequestEntries(body)` reads a request's body into its words, and `readRequestValues(form, entries)` checks a request the same way in the browser and in the CMS, with issues by field (`required`, `too-long`, `invalid-phone`, `invalid-email`, `unknown-option`) and their texts (`REQUEST_ISSUE_TEXTS`).
+- The events `seamlet:request-send` (cancelable), `seamlet:request-sent` and `seamlet:request-failed` on the form let the site's code send a request its own way or follow it.
+
+A site with forms needs a CMS that reads descriptions of 1.3 (cms.seamlet.ru from its release that takes requests). Code with an exhaustive `switch` over `SiteDescriptionProblem` gets its new members to handle.
+
 ## 1.2.1
 
 - `site.staticPaths(content)` is what Astro's `GetStaticPaths` takes: a static site's `[...page]` route may write `satisfies GetStaticPaths` and read its props with `InferGetStaticPropsType`. `StaticPage` and `RenderedPage` became type aliases, and `staticPaths` returns a mutable array.

package/README.md

@@ -128,6 +128,7 @@ The site's pages take their published content with `site.loadPublishedContent()`
 | `time({ label })`                          | `HH:MM`, 00:00 to 23:59                                                 | `null`           |
 | `slug({ label })`                          | the address of a record's page, `latte` in `/menu/latte` (below)        | `""`             |
 | `image({ label })`                         | `{ src, alt }`                                                          | `null`           |
+| `file({ label })`                          | `{ src, name }`: a PDF uploaded in the CMS, a price list or a menu      | `null`           |
 | `link({ label })`                          | `{ text, href }`: a page of the site, another site, a phone or an email | `null`           |
 | `url({ label })`                           | a web address without a text: a booking widget, a map                   | `null`           |
 | `toggle({ label })`                        | `true` or `false`                                                       | `false`          |
@@ -138,6 +139,16 @@ The site's pages take their published content with `site.loadPublishedContent()`
 | `group({ label, fields })`                 | named fields shown together                                             | each field empty |
 | `collection({ label, item, itemTitle? })`  | a list of records of the same fields                                    | `[]`             |
 
+A file is a document the owner uploads in the CMS as a PDF. The site links to it, and a static build copies it next to its pages as it copies the uploaded photos:
+
+```astro
+{content.priceList && (
+  <a href={safeHref(content.priceList.src)} download>
+    {content.priceList.name}
+  </a>
+)}
+```
+
 Options are `{ value, label }`: the site reads `value`, the editor shows `label`, so a label can change without touching the site. The content has their exact type:
 
 ```ts
@@ -362,6 +373,71 @@ A field is edited where it is seen, so the editor opens what hides it when a per
 
 What was opened stays open while the page is rendered anew after every edit: a part is known again by its `id`, or else by the field marked on it, in it or around it.
 
+## Requests
+
+A visitor sends the business a request from the site: «Обратный звонок», «Рассчитать стоимость», «Бронь столика». The site declares its forms, gives them to `defineSeamletSite` and renders them; the CMS keeps every request a year, writes to the people who edit the site and passes it on where the site's developer says.
+
+```ts
+// src/forms.ts
+import {
+  requestChoice,
+  requestForm,
+  requestLongText,
+  requestPhone,
+  requestText,
+} from "@seamlet/astro/schema";
+
+export const estimateForm = requestForm({
+  id: "estimate",
+  title: "Рассчитать стоимость",
+  fields: {
+    name: requestText({ label: "Имя", required: true }),
+    phone: requestPhone({ label: "Телефон", required: true }),
+    size: requestChoice({ label: "Размер", options: ["6×4", "6×6"] }),
+    comment: requestLongText({ label: "Комментарий", maxLength: 1000 }),
+  },
+});
+```
+
+```ts
+// src/seamlet.ts
+export default defineSeamletSite({
+  schema,
+  initialContent,
+  pages,
+  forms: [estimateForm],
+});
+```
+
+```astro
+---
+import RequestForm from "@seamlet/astro/components/RequestForm.astro";
+import { estimateForm } from "../forms";
+---
+
+<RequestForm form={estimateForm} submitLabel="Рассчитать" />
+```
+
+The fields are `requestText` (a line), `requestLongText` (several lines), `requestPhone`, `requestEmail` and `requestChoice` (one of `options`); each may be `required`, and a text has a `maxLength` (200 for a line, 2000 for several by default). A field's name is a name such as `phone` or `preferredTime`. The form's `title` names its requests in the CMS and in the letters.
+
+`RequestForm.astro` renders plain elements with classes (`seamlet-form`, `seamlet-form-field`, `seamlet-form-issue`, `seamlet-form-consent`, `seamlet-form-policy`, `seamlet-form-submit`, `seamlet-form-sent`, `seamlet-form-failed`), which the site styles from around it: `.contacts :global(.seamlet-form-field)`. Its props are the `form`, the words of the button (`submitLabel`), what the visitor reads once the request is sent or could not be (`sentText`, `failedText`), the addresses of the texts of consent and of the policy (`consentHref`, `policyHref`, the CMS's pages of them by default) and `instance`, which tells apart two forms of the same id on one page.
+
+The visitor consents with a checkbox of its own, never checked beforehand, to the texts the business confirmed in the CMS: until then the CMS takes no requests of the site, and the form says it could not send. Without a script the form is posted to the CMS, which answers with a page of its own; with the package's script (on every page, loaded only where a form is) the visitor stays on the page. The script checks what was typed with the code the CMS checks it with (`readRequestValues`), says what to fix under each field and sends the request.
+
+The site's own code hears every step from events on the form element, which bubble:
+
+- `seamlet:request-send` (`REQUEST_SEND_EVENT`), before the request is sent, with `{ form, entries }`. Cancelable: after `event.preventDefault()` the package sends nothing, and the site sends the request its own way.
+- `seamlet:request-sent` (`REQUEST_SENT_EVENT`), once the CMS has kept it, with `{ form, entries, id }`: a goal of the site's analytics, its own message.
+- `seamlet:request-failed` (`REQUEST_FAILED_EVENT`), with `{ form, reason, issues }`; `reason` is `invalid`, `closed` (the business takes no requests yet), `too-many` or `unavailable`.
+
+```ts
+document.addEventListener(REQUEST_SENT_EVENT, (event) => {
+  ym(COUNTER, "reachGoal", event.detail.form);
+});
+```
+
+A site whose `Content-Security-Policy` sets `connect-src` or `form-action` lets the CMS's origin in both. A request the policy stops on its way is posted by the browser as a plain form.
+
 ## What the integration adds
 
 - `/preview` and `/preview/<page>`: the preview the CMS's editor frames, the pages of records too (at their address or at the record's id, a page the site does not show too). `GET` shows the published content; `POST` with the content as JSON shows that content without saving it, which is how the editor shows every edit at once. Only the CMS may frame it (`Content-Security-Policy: frame-ancestors`), and it is never indexed or cached; its refusals (an address of no page, a record a draft does not have, a draft that is not JSON or is over 1 MB) say the same.

package/components/RequestForm.astro

@@ -0,0 +1,192 @@
+---
+// A form of the site's requests as plain elements, which the site styles from around it
+// (`.contacts :global(.seamlet-form-field)`). Without a script it is a form posted to the CMS, and
+// the CMS answers with a page of its own; the package's script sends it in place. The checkbox of
+// consent stands apart from the fields and is never checked beforehand, as the law asks: the
+// visitor consents to the texts of the business, which the CMS shows at their addresses.
+import { cmsOrigin, siteId } from "virtual:seamlet/config";
+import {
+  legalPagePathOf,
+  maxLengthOf,
+  REQUEST_CONSENT_KEY,
+  REQUEST_FORM_KEY,
+  REQUEST_PAGE_KEY,
+  REQUEST_TRAP_KEY,
+  requestsPathOf,
+  type RequestField,
+  type RequestForm,
+} from "@seamlet/astro/schema";
+
+interface Props {
+  readonly form: RequestForm;
+  /** The words of the button. */
+  readonly submitLabel?: string;
+  /** What the visitor reads once the business has the request. */
+  readonly sentText?: string;
+  /** What the visitor reads when the request could not be sent. */
+  readonly failedText?: string;
+  /** Where the text of consent is: the CMS's page of it unless the site has its own. */
+  readonly consentHref?: string;
+  /** Where the business's policy is: the CMS's page of it unless the site has its own. */
+  readonly policyHref?: string;
+  /** Tells two forms of the same id on one page apart, in the ids of their elements. */
+  readonly instance?: string;
+  readonly class?: string;
+}
+
+const {
+  form,
+  submitLabel = "Отправить",
+  sentText = "Спасибо! Заявка отправлена, мы скоро свяжемся с вами.",
+  failedText = "Не получилось отправить заявку. Попробуйте ещё раз чуть позже.",
+  consentHref = new URL(legalPagePathOf(siteId, "consent"), cmsOrigin).href,
+  policyHref = new URL(legalPagePathOf(siteId, "privacy"), cmsOrigin).href,
+  instance = form.id,
+  class: className,
+} = Astro.props;
+
+const action = new URL(requestsPathOf(siteId), cmsOrigin).href;
+const fields = Object.entries(form.fields);
+const idOf = (name: string) => `seamlet-${instance}-${name}`;
+const issueIdOf = (name: string) => `${idOf(name)}-issue`;
+/** The page the form stands on, so the business knows where the request came from. */
+const page = Astro.url.pathname;
+/** A field typed on one line of an `<input>`. */
+type LineField = Extract<RequestField, { kind: "text" | "phone" | "email" }>;
+const INPUT_TYPES: Readonly<Record<LineField["kind"], string>> = {
+  text: "text",
+  phone: "tel",
+  email: "email",
+};
+/** What a phone's keyboard and a browser's memory of addresses offer for a field. */
+const AUTOCOMPLETE: Partial<Record<LineField["kind"], string>> = {
+  phone: "tel",
+  email: "email",
+};
+const isLineField = (field: RequestField): field is LineField =>
+  field.kind === "text" || field.kind === "phone" || field.kind === "email";
+---
+
+<form
+  class:list={["seamlet-form", className]}
+  method="post"
+  action={action}
+  data-seamlet-form={form.id}
+  data-seamlet-request-form={JSON.stringify(form)}
+>
+  <input type="hidden" name={REQUEST_FORM_KEY} value={form.id} />
+  <input type="hidden" name={REQUEST_PAGE_KEY} value={page} />
+  {fields.map(([name, field]) => (
+    <div class="seamlet-form-field" data-field={name}>
+      <label for={idOf(name)}>
+        {field.label}
+        {field.required === true && <span aria-hidden="true"> *</span>}
+      </label>
+      {field.kind === "longText" && (
+        <textarea
+          id={idOf(name)}
+          name={name}
+          rows="4"
+          required={field.required === true}
+          maxlength={maxLengthOf(field)}
+          aria-describedby={issueIdOf(name)}
+        />
+      )}
+      {field.kind === "choice" && (
+        <select
+          id={idOf(name)}
+          name={name}
+          required={field.required === true}
+          aria-describedby={issueIdOf(name)}
+        >
+          <option value="">Выберите</option>
+          {field.options.map((option) => (
+            <option value={option}>{option}</option>
+          ))}
+        </select>
+      )}
+      {isLineField(field) && (
+        <input
+          id={idOf(name)}
+          name={name}
+          type={INPUT_TYPES[field.kind]}
+          required={field.required === true}
+          maxlength={field.kind === "text" ? maxLengthOf(field) : undefined}
+          autocomplete={AUTOCOMPLETE[field.kind]}
+          aria-describedby={issueIdOf(name)}
+        />
+      )}
+      <p
+        class="seamlet-form-issue"
+        id={issueIdOf(name)}
+        data-seamlet-issue={name}
+        hidden
+      />
+    </div>
+  ))}
+  <div class="seamlet-form-trap" aria-hidden="true">
+    <label>
+      Это поле заполнять не нужно
+      <input
+        type="text"
+        name={REQUEST_TRAP_KEY}
+        tabindex="-1"
+        autocomplete="off"
+      />
+    </label>
+  </div>
+  <div class="seamlet-form-consent">
+    <input
+      id={idOf(REQUEST_CONSENT_KEY)}
+      type="checkbox"
+      name={REQUEST_CONSENT_KEY}
+      value="on"
+      required
+      aria-describedby={issueIdOf(REQUEST_CONSENT_KEY)}
+    />
+    <label for={idOf(REQUEST_CONSENT_KEY)}>
+      Даю{" "}
+      <a href={consentHref} target="_blank" rel="noopener">
+        согласие на обработку персональных данных
+      </a>
+    </label>
+    <p
+      class="seamlet-form-issue"
+      id={issueIdOf(REQUEST_CONSENT_KEY)}
+      data-seamlet-issue={REQUEST_CONSENT_KEY}
+      hidden
+    />
+  </div>
+  <p class="seamlet-form-policy">
+    <a href={policyHref} target="_blank" rel="noopener">
+      Политика обработки персональных данных
+    </a>
+  </p>
+  <button class="seamlet-form-submit" type="submit">
+    {submitLabel}
+  </button>
+  <p
+    class="seamlet-form-sent"
+    role="status"
+    tabindex="-1"
+    data-seamlet-sent
+    data-seamlet-text={sentText}
+  />
+  <p
+    class="seamlet-form-failed"
+    role="alert"
+    data-seamlet-failed
+    data-seamlet-text={failedText}
+  />
+</form>
+
+<style>
+  /* Out of sight and out of reach of the keyboard, yet a field a program fills. */
+  .seamlet-form-trap {
+    position: absolute;
+    left: -10000px;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+  }
+</style>

package/dist/bridge.d.ts

@@ -1,5 +1,5 @@
-import { F as Fields } from './parse-content-Bnn6Wa-l.js';
-import { P as PageMessage, E as EditorMessage } from './messages-C2OjqFmy.js';
+import { F as Fields } from './parse-content-CT2cUVL-.js';
+import { P as PageMessage, E as EditorMessage } from './messages-Dwjthhrk.js';
 
 interface BridgeOptions {
     /** The origin of the CMS whose editor may frame the page, such as `https://cms.example.com`. */

package/dist/bridge.js

@@ -18,7 +18,7 @@ import {
   shortcutOf,
   toggleList,
   toggleMark
-} from "./chunk-Y4R4YV5O.js";
+} from "./chunk-BCJUH3ZD.js";
 import {
   FIELD_PATH_ATTRIBUTE,
   REVEALED_ATTRIBUTE,
@@ -28,7 +28,7 @@ import {
   readRichText,
   resolveFieldPath,
   safeHref
-} from "./chunk-UL2C2IB2.js";
+} from "./chunk-TMN7KG5M.js";
 
 // src/bridge/typed-fields.ts
 function typedKindAt(schema, path) {
@@ -44,6 +44,7 @@ function typedKindAt(schema, path) {
     case "time":
     case "slug":
     case "image":
+    case "file":
     case "link":
     case "url":
     case "toggle":

package/dist/chunk-2IK7D2AA.js

@@ -0,0 +1,6 @@
+// src/request-form-markers.ts
+var REQUEST_FORM_SELECTOR = "form[data-seamlet-form]";
+
+export {
+  REQUEST_FORM_SELECTOR
+};

package/dist/{chunk-Y4R4YV5O.js → chunk-BCJUH3ZD.js}

@@ -6,7 +6,7 @@ import {
   readRichText,
   resolveFieldPath,
   safeHref
-} from "./chunk-UL2C2IB2.js";
+} from "./chunk-TMN7KG5M.js";
 
 // src/bridge/editor-shortcuts.ts
 function shortcutOf(event) {

package/dist/{chunk-OCA2WYK3.js → chunk-JQ4YD7MM.js}

@@ -1,6 +1,6 @@
 import {
   pagePathOf
-} from "./chunk-HFPZVDST.js";
+} from "./chunk-ULOKDC6D.js";
 import {
   FIELD_PATH_SEPARATOR,
   collectionAt,
@@ -9,7 +9,7 @@ import {
   newRecord,
   recordAt,
   recordPageAt
-} from "./chunk-UL2C2IB2.js";
+} from "./chunk-TMN7KG5M.js";
 
 // src/preview-requests.ts
 var MAX_DRAFT_BYTES = 1024 * 1024;
@@ -17,6 +17,7 @@ var BAD_REQUEST = 400;
 var PAYLOAD_TOO_LARGE = 413;
 var UNSUPPORTED_MEDIA_TYPE = 415;
 var UPLOADED_PHOTO = /^[A-Za-z0-9_-]+\.webp$/u;
+var UPLOADED_FILE = /^[A-Za-z0-9_-]+\.(?:webp|pdf)$/u;
 function previewHeadersOf(cmsOrigin) {
   return {
     "Content-Security-Policy": `frame-ancestors ${cmsOrigin}`,
@@ -57,6 +58,9 @@ function previewContentAt(description, content, rest) {
 function isUploadedPhoto(fileName) {
   return fileName !== void 0 && UPLOADED_PHOTO.test(fileName);
 }
+function isUploadedFile(fileName) {
+  return fileName !== void 0 && UPLOADED_FILE.test(fileName);
+}
 async function readLimited(request) {
   if (request.body === null) return "";
   const reader = request.body.getReader();
@@ -100,5 +104,6 @@ export {
   readDraft,
   isPageAddress,
   previewContentAt,
-  isUploadedPhoto
+  isUploadedPhoto,
+  isUploadedFile
 };