efficient-web-builder 0.8.1 → 0.10.0

package/dist/index.d.ts

@@ -221,6 +221,22 @@ export type SaveExpectation = {
 };
 
 /** A set of pages: a website's, or one template's. */
+/**
+ * A page a link can point at: enough to name it, and its layout — where its
+ * section anchors are read from, and how the editor tells which page holds a
+ * section a link may open in a particular state.
+ */
+export interface LinkTargetPage {
+  id: string;
+  /** The page's handle. A link to the page is built from this. */
+  slug: string;
+  /** The page's name as a list shows it. */
+  label: string;
+  /** The page's layout, or null when the backend does not hand it out with the
+   *  list. Without it the page is still a link target; its anchors are not. */
+  layout: PageLayout | null;
+}
+
 export interface WebsitePages {
   /** The rows the page list navigates between. */
   list(scope?: SiteScope): Promise<EditorPageRow[]>;
@@ -244,6 +260,12 @@ export interface WebsitePages {
   create?(input: NewPageInput): Promise<EditorPageRow>;
   /** Delete a page from the page list. */
   remove?(id: string): Promise<void>;
+  /**
+   * Every page of the website a link may point at, each with its layout — in
+   * ONE call, for the link picker. Optional: without it the picker lists the
+   * rows of {@link list} and offers no section anchors.
+   */
+  linkTargets?(scope?: SiteScope): Promise<LinkTargetPage[]>;
 }
 
 /** The other operator, as the editor's notices describe them. */
@@ -310,6 +332,13 @@ export interface WebsiteMedia {
   /** RESERVED: upload a file dropped on a media field. 0.4.0 hands a dropped
    *  file to the host's media panel or picker and does not call it. */
   upload?(file: File): Promise<HostPickedMedia>;
+  /**
+   * The largest file a media field takes, in bytes. A larger one is refused
+   * where it was dropped, with the reason, before it is handed to the host's
+   * media panel or picker. Without it the editor refuses no file for its size —
+   * the host's own picker has the say.
+   */
+  maxUploadBytes?: number;
 }
 
 /** One node of a page document: a section or a block, with its own props. */
@@ -358,13 +387,157 @@ export interface WebsitePreview {
   href(slug: string): string;
 }
 
+/**
+ * A blog post, as the editor lists one: enough to name it, link to it and draw a
+ * card from it. Published posts only — a draft is not something a page links to.
+ */
+export interface BlogPostRow {
+  /** The post's stable handle. A block that is linked to a post stores this. */
+  slug: string;
+  title: string;
+  /** The standfirst. Empty when the post has none. */
+  excerpt: string;
+  /** The post's editorial category, as its author typed it. Empty when none. */
+  category: string;
+  /** The cover picture's address, absolute — or "" when the post has none. */
+  coverImage: string;
+  /** When it was published (ISO 8601), or null. */
+  publishedAt: string | null;
+  /** Where the post lives on the website, as a path (`/journal/first-post`). */
+  href: string;
+}
+
+/**
+ * The website's blog. Optional: without it the editor lists no post — a block's
+ * "Blog post source" shows only what it is already linked to, and the link
+ * picker offers no "Blog post" (`EditorCapabilities.hasBlog`).
+ */
+export interface WebsiteBlog {
+  /** The website's published posts, in the order the website lists them. */
+  posts(scope?: SiteScope): Promise<BlogPostRow[]>;
+}
+
+/** The website's live-chat bubble: whether it shows, and its three lines.
+ *  A blank line means "the widget's own wording". */
+export interface ChatSettings {
+  enabled: boolean;
+  title: string;
+  subtitle: string;
+  greeting: string;
+}
+
+/**
+ * The website's live chat. Optional: without it the editor's "Live chat" panel
+ * previews a change and saves nothing, and starts from the house default.
+ */
+export interface WebsiteChat {
+  get(scope?: SiteScope): Promise<ChatSettings>;
+  /** Store the lines that changed; answer the settings as they now stand. */
+  update(patch: Partial<ChatSettings>, scope?: SiteScope): Promise<ChatSettings>;
+}
+
+/**
+ * A website's appearance as it is stored: its colour themes, type, corners,
+ * cards and widths — the row behind the Site styles panel. The keys are the
+ * stored ones. Every key but `id` and the first run is optional or nullable:
+ * absent and `null` both mean "not set", and the website draws the built-in
+ * look for it.
+ */
+export interface SiteThemeRow {
+  id: string;
+  selected_preset: number;
+  theme_presets: {
+    text: string;
+    accent: string;
+    background?: string;
+    surface?: string;
+    line?: string;
+    muted?: string;
+    button?: string;
+    buttonInk?: string;
+  }[];
+  accent_color?: string | null;
+  heading_font: string;
+  body_font: string;
+  accent_font: string;
+  label_font: string;
+  default_mode: "light" | "dark" | "auto";
+  show_theme_switch: boolean;
+  heading_scale: number;
+  body_scale: number;
+  label_scale: number;
+  heading_size_large_px?: number | null;
+  heading_size_medium_px?: number | null;
+  heading_size_small_px?: number | null;
+  accent_size_px?: number | null;
+  body_size_px?: number | null;
+  label_size_px?: number | null;
+  corner_style: "square" | "small" | "large";
+  corner_radius_px?: number | null;
+  heading_compression: "normal" | "tight" | "compressed";
+  card_shadow?: "none" | "soft" | "lifted" | null;
+  shadow_color?: string | null;
+  card_gap: "tight" | "normal" | "roomy";
+  hover_effect?: "none" | "lift" | "highlight" | null;
+  heading_case?: "authored" | "sentence" | null;
+  heading_weight?: number | null;
+  heading_weight_strong?: number | null;
+  heading_2_weight?: number | null;
+  heading_3_weight?: number | null;
+  heading_2_case?: "authored" | "sentence" | null;
+  heading_3_case?: "authored" | "sentence" | null;
+  heading_max_px?: number | null;
+  site_width?: number | null;
+  site_gutter?: number | null;
+  block_gap?: number | null;
+  hero_background_follows_width?: boolean | null;
+  photography_grayscale?: boolean | null;
+  word_styles?: Partial<Record<string, Record<string, unknown> | null>> | null;
+}
+
+/** What may be written: any of a {@link SiteThemeRow} but its own id. */
+export type SiteThemeRowPatch = Partial<Omit<SiteThemeRow, "id">>;
+
+/**
+ * The website's appearance. Optional: without it the editor has no stored
+ * appearance to open on or save to — no Site styles — and a website is drawn
+ * in the built-in look.
+ */
+export interface WebsiteTheme {
+  /** The row behind a website — its own, or the one it falls back to. Reading
+   *  must not create one. */
+  get(scope?: SiteScope): Promise<SiteThemeRow>;
+  /** Store the keys that changed; answer the row as it now stands. */
+  update(patch: SiteThemeRowPatch, scope?: SiteScope): Promise<SiteThemeRow>;
+}
+
+/** The website's social profile links: one address per platform, under the
+ *  platform's own name (`instagram`, `facebook`, …). "" where there is none. */
+export type SocialLinkSettings = Record<string, string>;
+
+/**
+ * The website's social links. Optional: without it the editor's Social links
+ * rows — and a footer's Social block — show no saved link and save none.
+ */
+export interface WebsiteSocial {
+  get(scope?: SiteScope): Promise<SocialLinkSettings>;
+  /**
+   * Store the links named; answer every link as it now stands. Reject
+   * `invalid` with `fields` — the platform refused, and the reason to show
+   * beside its box — when an address is not one.
+   */
+  update(patch: SocialLinkSettings, scope?: SiteScope): Promise<SocialLinkSettings>;
+}
+
 /**
  * Everything the editor asks a server for.
  *
  * Other groups the editor still reads from the EFFICIENT client directly — the
- * site's theme, header, social links and live chat, menus, blog, forms and the
- * catalog — join this interface as optional members when their call sites move.
- * Until then a backend other than EFFICIENT's gets the page editor without them.
+ * site's header, menus, forms and the catalog — join this interface as
+ * optional members when their call sites move. Until then a backend other than
+ * EFFICIENT's gets the page editor without them. The blog (`blog`), the live
+ * chat (`chat`), the social links (`social`) and the site's appearance
+ * (`theme`) have crossed.
  */
 export interface WebsiteBackend {
   pages: WebsitePages;
@@ -374,6 +547,10 @@ export interface WebsiteBackend {
   sectionTemplates?: WebsiteSectionTemplates;
   templates?: WebsiteTemplates;
   preview?: WebsitePreview;
+  blog?: WebsiteBlog;
+  chat?: WebsiteChat;
+  social?: WebsiteSocial;
+  theme?: WebsiteTheme;
 }
 
 /** Why a backend call failed, in the editor's own terms. */
@@ -405,10 +582,13 @@ export class WebsiteBackendError extends Error {
   readonly conflict?: SaveConflict;
   /** `lock-taken`: who holds the page. */
   readonly holder?: LockHolder;
+  /** `invalid`: the inputs that were refused, by name, each with the reason —
+   *  when the backend can say which. The editor shows it beside that input. */
+  readonly fields?: Readonly<Record<string, string>>;
   constructor(
     kind: WebsiteBackendErrorKind,
     message?: string,
-    detail?: { conflict?: SaveConflict; holder?: LockHolder; cause?: unknown },
+    detail?: { conflict?: SaveConflict; holder?: LockHolder; fields?: Readonly<Record<string, string>>; cause?: unknown },
   );
 }