@wix/blog 1.0.690 → 1.0.692

package/_sdk-exports/context-blog-feed-context-provider/runtime.d.ts

@@ -0,0 +1,483 @@
+import React from "react";
+
+//#region ../../node_modules/@wix/editor-react-types/dist/links.d.ts
+type LinkTarget = '_self' | '_blank';
+/**
+ * A link to a URL, used for navigation within components.
+ *
+ * @example
+ * ```tsx
+ * import type { Link } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   link?: Link;
+ * }
+ * ```
+ */
+type Link = {
+  /**
+   * The link URL. For partial links (see `pageRole`), this is the router prefix
+   * (e.g. `https://www.my-site.com/prefix`) rather than a fully resolved URL.
+   */
+  href?: string;
+  /**
+   * Where this link should open.
+   * - `'_self'` — opens in the same page.
+   * - `'_blank'` — opens in a new tab.
+   */
+  target?: LinkTarget; /** The `rel` attribute of the link. Accepts LinkRel values separated by a space. */
+  rel?: string;
+  /**
+   * Page role identifier. Present only on partial links, where only the router prefix is
+   * known and the full URL format is owned by the Router/App. Applications can use such
+   * links in functions to resolve the complete URL at runtime (e.g. for binding links).
+   * Resolved links will not have this field.
+   */
+  pageRole?: string;
+};
+//#endregion
+//#region ../../node_modules/@wix/editor-react-types/dist/image.d.ts
+type Point = {
+  x: number;
+  y: number;
+};
+type Crop = Point & {
+  width: number;
+  height: number;
+};
+/**
+ * An image from Wix Media.
+ *
+ * @example
+ * ```tsx
+ * import type { Image } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   image?: Image;
+ * }
+ *
+ * const MyComponent = ({ image }: MyComponentProps) => (
+ *   <img src={image?.url} alt={image?.alt} />
+ * );
+ * ```
+ */
+type Image = {
+  /** The image URI. */uri?: string; /** The image URL. */
+  url: string; /** The image file name. */
+  name?: string; /** The image height in pixels. */
+  height?: number; /** The image width in pixels. */
+  width?: number; /** Whether the image is animated (e.g. GIF). */
+  animated?: boolean; /** The crop region applied to the image. */
+  crop?: Crop; /** The image quality, as a percentage from 0 to 100. */
+  quality?: number; /** The image alt text for accessibility. */
+  alt?: string;
+};
+//#endregion
+//#region ../../node_modules/@wix/editor-react-types/dist/base.d.ts
+/**
+ * A standard email address according to RFC 5321, section 4.1.2.
+ *
+ * @example
+ * ```tsx
+ * import type { Email } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   contactEmail?: Email;
+ * }
+ * ```
+ */
+type Email = string;
+/**
+ * A phone number string, accepting common phone number characters.
+ *
+ * @example
+ * ```tsx
+ * import type { Phone } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   phoneNumber?: Phone;
+ * }
+ * ```
+ */
+type Phone = string;
+/**
+ * Rich text content with resolved links.
+ *
+ * @example
+ * ```tsx
+ * import type { RichText } from '@wix/editor-react-types';
+ *
+ * interface MyComponentProps {
+ *   description?: RichText;
+ * }
+ *
+ * const MyComponent = ({ description }: MyComponentProps) => (
+ *   <div>
+ *     {description?.html}
+ *     {description?.linkList.map((link) => (
+ *       <a key={link.href} href={link.href}>{link.href}</a>
+ *     ))}
+ *   </div>
+ * );
+ * ```
+ */
+type RichText = {
+  /** The original rich text content. */text: string; /** The HTML content with all links resolved. */
+  html: string; /** All links present in the rich text content. */
+  linkList: Array<Link>;
+};
+//#endregion
+//#region ../../node_modules/@wix/editor-react-types/dist/visualMedia.d.ts
+interface VisualMediaBase {
+  /** The URL of the media file */
+  src: string;
+  /** The slug for the media */
+  slug?: string;
+  /** Description of the media for accessibility purposes */
+  description?: string | RichText;
+  /** The title of the media */
+  title?: string | RichText;
+  /** The height of the media in pixels */
+  height?: number;
+  /** The width of the media in pixels */
+  width?: number;
+  /** An action when the item is clicked */
+  action?: {
+    /** The URL to navigate to when the media is clicked */link: Link | Phone | Email;
+  };
+}
+type VisualMedia = (VisualMediaBase & {
+  type: 'image'; /** Additional parameters specific to images, such as focal point and alt text. */
+  parameters?: ImageParameters;
+}) | (VisualMediaBase & {
+  type: 'video'; /** Additional parameters specific to videos, such as thumbnail, alt text, and whether the video has audio. */
+  parameters?: VideoParameters;
+});
+type VideoParameters = {
+  /** The URL of the video thumbnail */thumbnail?: string; /** Alternative text for the video */
+  alt?: string; /** Whether the video has audio */
+  hasAudio?: boolean;
+};
+type ImageParameters = {
+  /** The focal point for the image */focalPoint?: [number, number]; /** The alt text for the image */
+  alt?: string;
+};
+//#endregion
+//#region src/lib/category-picker.d.ts
+/** The inline filter field name, and therefore the key on the stored value. */
+declare const CATEGORY_PICKER_FIELD = "categoryId";
+/** A WQL clause the filter picker stores for one inline field. */
+type PickerClause = {
+  $eq?: string;
+  $in?: string[];
+};
+interface CategoryPickerFilter {
+  [CATEGORY_PICKER_FIELD]?: PickerClause;
+}
+//#endregion
+//#region src/lib/post-picker.d.ts
+/** The inline filter field name, and therefore the key on the stored value. */
+declare const POST_PICKER_FIELD = "postId";
+interface PostPickerFilter {
+  [POST_PICKER_FIELD]?: PickerClause;
+}
+//#endregion
+//#region src/i18n/post-labels.types.d.ts
+/** Display-ready copy for the Repeater's bindable `emptyState: {title, description}` prop. */
+interface EmptyStateLabels {
+  title: string;
+  description: string;
+}
+//#endregion
+//#region ../../node_modules/type-fest/source/observable-like.d.ts
+declare global {
+  // eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
+  interface SymbolConstructor {
+    readonly observable: symbol;
+  }
+}
+/**
+@remarks
+The TC39 observable proposal defines a `closed` property, but some implementations (such as xstream) do not as of 10/08/2021.
+As well, some guidance on making an `Observable` to not include `closed` property.
+@see https://github.com/tc39/proposal-observable/blob/master/src/Observable.js#L129-L130
+@see https://github.com/staltz/xstream/blob/6c22580c1d84d69773ee4b0905df44ad464955b3/src/index.ts#L79-L85
+@see https://github.com/benlesh/symbol-observable#making-an-object-observable
+
+@category Observable
+*/
+//#endregion
+//#region ../../node_modules/@wix/sdk-types/build/index.d.ts
+declare global {
+  interface ContextualClient {}
+}
+/**
+ * Creates concrete types from SDK descriptors when a contextual client is
+ * available.
+ *
+ * For a REST descriptor the built (bound) API is intersected with the original
+ * descriptor, matching what `contextualizeRESTModuleV2` returns at runtime — a
+ * value callable as the bound API and still usable as a descriptor. Keeping the
+ * descriptor half lets contextual modules be passed to descriptor-constrained
+ * helpers such as `elevate` from `@wix/sdk/context` (FEDINF-14092).
+ *
+ * The `& T` is scoped to REST descriptors — the only shape codegen wraps in
+ * `MaybeContext` — so `BuildDescriptors` (used by `createClient().use`) is left
+ * unchanged and stays bound-only. The fix lives here rather than in `elevate`,
+ * which is kept strict on purpose (see #941) so it still rejects bound-only
+ * functions that are unsafe through `createRESTModule`.
+ */
+declare global {
+  /**
+   * A global interface to set the exposure toggle for the SDK.
+   * @example
+   * ```ts
+   * declare global {
+   *  interface SDKExposureToggle {
+   *    alpha: true;
+   *  }
+   * }
+   */
+  interface SDKExposureToggle {}
+}
+declare global {
+  /**
+   * A global interface to set the type mode for the SDK.
+   * @example
+   * ```ts
+   * declare global {
+   *  interface SDKTypeMode {
+   *    strict: true;
+   *  }
+   * }
+   */
+  interface SDKTypeMode {}
+}
+//#endregion
+//#region src/lib/parse-post-cover-media.d.ts
+/** One playable rendition of a Wix-hosted cover video (a raw REST `VideoResolution`). */
+interface VideoSource {
+  url: string;
+  width?: number;
+  height?: number;
+}
+type EmbedProvider = 'youtube' | 'vimeo' | 'unknown';
+/**
+ * The post cover as the Cover Media widget consumes it — a discriminated union over the
+ * `post.media` oneof: a Wix-hosted image, a Wix-hosted video (`wixMedia.videoV2`), or an
+ * externally hosted embed (`embedMedia`, YouTube/Vimeo).
+ */
+type CoverMedia = {
+  kind: 'image';
+  image: Image;
+} | {
+  kind: 'wixVideo'; /** The WixMedia video id — the `wix:video://v1/<id>/...` path segment. */
+  id: string;
+  posterUrl?: string;
+  posterWidth?: number;
+  posterHeight?: number;
+  /**
+   * Playable mp4 renditions, optimal-first. Empty when the raw REST join was
+   * unavailable — the widget then renders the poster alone (see post-video-api.ts
+   * for why the SDK's `videoV2` string cannot carry these).
+   */
+  sources: VideoSource[];
+  altText: string;
+} | {
+  kind: 'embed';
+  provider: EmbedProvider; /** The author-supplied external video URL, as the Blog API stores it. */
+  videoUrl: string; /** Provider player URL for click-to-play; absent for an unrecognized provider. */
+  embedUrl?: string;
+  thumbnailUrl?: string;
+  thumbnailWidth?: number;
+  thumbnailHeight?: number;
+  altText: string;
+};
+//#endregion
+//#region src/extensions/post-list-context-provider/utils.d.ts
+/**
+ * One item of the `postsList` array — the object the platform hands the Post Item
+ * context provider as its `postData` prop (via the manifest's `contextImplementor`).
+ * The `item*`/`recentPostItem` keys must match the Post Item context manifest's
+ * `context.items` keys — the runtime resolves an element's binding by looking the key
+ * up on the per-item hook's return value.
+ */
+interface PostListItem {
+  /** Repeater item identity; also the manifest contract's `_id`. */
+  _id: string;
+  /** The manifest contract's `title` (plain text, non-bindable — see `itemTitle` below). */
+  title: string;
+  itemTitle: RichText;
+  itemExcerpt: RichText;
+  itemCoverImage: Image | undefined;
+  /**
+   * The cover as the Cover Media widget renders it — image OR playable video, where
+   * `itemCoverImage` above can only ever be the image. Runtime-only by design: deliberately
+   * absent from `POST_ITEM_CONTRACT_ITEMS` and the Post Item manifest (the runtime injects
+   * the full item object regardless, and the manifest contract must stay text-scalars-only —
+   * see post-item-contract.ts). Not bindable in Connect Value; consumed via
+   * `usePostItemContext()` only.
+   */
+  itemCoverMedia: CoverMedia | undefined;
+  itemLink: Link | undefined;
+  itemPublishedDate: RichText;
+  /**
+   * Raw values for the compact widgets (Metadata, Counters), which format for themselves
+   * (a design-panel date/number format) instead of parsing the richText labels above.
+   * Runtime-only like `itemCoverMedia` — never bindable items. JSON-safe on purpose (ISO
+   * string, numbers): the item crosses the platform's per-cell prop injection, and a `Date`
+   * would not survive the round-trip.
+   */
+  /** ISO 8601; `undefined` for a post without `firstPublishedDate`. */
+  publishedDateValue: string | undefined;
+  /**
+   * The clock `itemPublishedDate` was formatted from (`useHydrationClock`) — the compact
+   * widgets format `publishedDateValue` for themselves and must use the same one, or their
+   * label would hydrate against a different "now" than the bound text did.
+   */
+  clockValue: number;
+  /** `undefined` when absent OR 0 — the same API-artifact rule as `timeToRead` below. */
+  minutesToReadValue: number | undefined;
+  /**
+   * The server-side METRICS counters as raw numbers, the seed the Post Item provider
+   * publishes as `viewCountValue`/`commentCountValue` until its client-only metrics read
+   * lands (and for good in the editor, where that read is skipped). Same three-way rule as
+   * the `viewCount`/`commentCount` labels: metric → canvas stand-in → `undefined`, never 0.
+   */
+  initialViewCount: number | undefined;
+  initialCommentCount: number | undefined;
+  /**
+   * The remaining keys reuse the Post context's names verbatim — the registry is per app and
+   * keyed by item path, so re-declaring a key at the same dataType on the Post Item context
+   * costs no new registry rows (the same trick `likeCount` already relies on).
+   */
+  authorName: RichText;
+  authorImage: Image | undefined;
+  timeToRead: RichText;
+  /**
+   * Resolved in priority order by `counterLabel`:
+   *   1. the post's own `metrics` (the `METRICS` fieldset) — renders everywhere, including
+   *      the editor canvas and inside SSR HTML;
+   *   2. an editor stand-in, when the API answers without metrics;
+   *   3. blank, for the Post Item provider to fill in from its per-cell metrics read.
+   *
+   * Blank rather than zero at step 3 because a seeded "0 views" reads as a confident wrong
+   * number until that read lands. Step 1 exists because step 3 alone is not enough: the
+   * per-cell read is client-only by design (personal data must never bake into SSR HTML the
+   * host caches for days) AND is skipped outright in the editor, which left a bound counter
+   * permanently blank on the canvas.
+   */
+  viewCount: RichText;
+  commentCount: RichText;
+  /**
+   * The post's MAIN category label — one, not a list. blog-client's feed card renders a single
+   * category (`post.categoryIds[0]`); its multi-category `CategoryLabelList` was built for the
+   * feed and never shipped, and the 3-chip list lives on the post page only.
+   */
+  itemCategoryLabel: RichText;
+  /** Mirrors the Post Item manifest's nested (non-bindable) `recentPostItem` data item. */
+  recentPostItem: {
+    title: string;
+    slug: string;
+  };
+  /**
+   * Whether the post takes new comments — the Comments widget's lock in a cell. Runtime-only
+   * like `itemCoverMedia`; `undefined` (partial fieldset, canvas stand-in) reads as unlocked.
+   */
+  commentingEnabled: boolean | undefined;
+}
+/** Display-ready copy for the Repeater's bindable `emptyState: {title, description}`
+ * prop (the manifest's `emptyState` item). The provider never renders it — the
+ * Repeater shows it (editor stage) when its bound items array is empty. The copy comes
+ * from the site-language labels (`PostLabels.noPostsEmptyState`). */
+type EmptyStateContent = EmptyStateLabels;
+//#endregion
+//#region src/extensions/post-list-context-provider/post-list-context-provider.d.ts
+/**
+ * Which feed view the page is showing, resolved from the URL and the fetched page — the
+ * Category Header widget's whole input (runtime-only, never a bindable `context.items` entry,
+ * so it freezes no manifest keys).
+ *
+ * `pending` is the Suspense fallback's value, NOT `all`: the fallback renders before the page
+ * resolves, and claiming `all` there would flash the "All Posts" label on a category URL.
+ * A slug that matched nothing resolves to `all` — a truthful empty feed makes no header claim.
+ *
+ * Only a category has a description and a cover; a tag carries a label alone (the Blog API's
+ * `BlogTag` has no such fields).
+ */
+type FilteredFeedView = {
+  kind: 'pending';
+} | {
+  kind: 'all';
+} | {
+  kind: 'category';
+  title: string;
+  description: string;
+  coverImage: Image | undefined;
+} | {
+  kind: 'tag';
+  title: string;
+};
+/** The blog feed: its posts, loading and error state, and paging, as read through {@link useBlogFeedContext}. */
+interface PostListContextType {
+  postsList: PostListItem[];
+  /**
+   * The manifest's `postGalleryItems` — the same posts as Fast Gallery `VisualMedia`
+   * items (cover + title + excerpt + post-page link). Coverless posts are filtered out:
+   * a bound gallery is a media wall, and a cell with no media is a broken cell.
+   */
+  postGalleryItems: VisualMedia[];
+  emptyState: EmptyStateContent | null;
+  /**
+   * The posts read failed and this feed is showing nothing it fetched — a bindable
+   * signal so a builder can put an error message (or a retry link) where the cards
+   * would be. Distinct from an empty feed on purpose: `emptyState` stays null while
+   * this is true, because "No posts yet" is a lie about a failed request.
+   */
+  hasError: boolean;
+  hasMorePosts: boolean;
+  isLoadingPosts: boolean;
+  loadMorePosts: () => Promise<void>;
+  /**
+   * Runtime-only (the Category Header widget reads it through this hook) — deliberately not a
+   * `context.items` entry: item keys and dataTypes freeze per app once pushed (error 6001).
+   */
+  filteredView: FilteredFeedView;
+}
+/** Reads the blog feed from the nearest feed context provider; throws outside one. */
+declare function useBlogFeedContext(): PostListContextType;
+/** Loads a page of blog posts, filtered by the URL view or the picked category or posts, and supplies them as a feed. */
+declare function PostListProvider({
+  children,
+  categoryPicker,
+  postsPicker,
+  pageSize,
+  postOffset,
+  sortOrder,
+  featuredOnly,
+  liveRefreshGeneration
+}: {
+  children?: React.ReactNode;
+  /**
+   * The manifest's `data.categoryPicker` filter — `{ categoryId: { $eq: '<id>' } }` as the
+   * editor's Items Selection picker stores it; absent/empty means unfiltered.
+   */
+  categoryPicker?: CategoryPickerFilter;
+  /**
+   * The manifest's `data.postsPicker` filter — `{ postId: { $in: ['<id>', ...] } }`; absent/empty
+   * means no hand-picked posts.
+   */
+  postsPicker?: PostPickerFilter; /** The manifest's `data.pageSize` input — unset/invalid falls back to 6. */
+  pageSize?: number; /** The manifest's `data.postOffset` input — unset/invalid falls back to 0 (no skip). */
+  postOffset?: number; /** The manifest's `data.sortOrder` select — unset/unknown falls back to 'newest'. */
+  sortOrder?: string; /** The manifest's `data.featuredOnly` toggle — unset means all posts. */
+  featuredOnly?: boolean;
+  /**
+   * Not a manifest input: the editor entry bumps it when the dashboard changes a post
+   * (`post-list-context-provider.editor.tsx`). Above 0 the first page skips the warmup
+   * slot (`key: null`), because a live refetch must never be answered from it.
+   */
+  liveRefreshGeneration?: number;
+}): React.ReactNode;
+//#endregion
+export { type EmptyStateContent, FilteredFeedView, PostListContextType, type PostListItem, PostListProvider, PostListProvider as default, useBlogFeedContext };