@wix/blog 1.0.690 → 1.0.692

package/_sdk-exports/context-post-item-context-provider/runtime.d.ts

@@ -0,0 +1,386 @@
+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
+/**
+ * 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/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;
+}
+//#endregion
+//#region src/hooks/post-likes.types.d.ts
+interface PostLikes {
+  isLiked: boolean;
+  /** Server count adjusted by the viewer's optimistic toggle delta. */
+  likeCount: number;
+  /**
+   * False while the fresh like-count read is in flight (always false on SSR) — the
+   * Counters widget renders a skeleton instead of a possibly-stale number until it flips.
+   * A skipped read (editor, preview, no post id) and a failed read both settle to true
+   * with the baked count, so the skeleton never outlives its fetch.
+   */
+  isLikeCountLoaded: boolean;
+  /**
+   * View and comment totals off the same metrics read, `undefined` until it lands (and for
+   * good on the editor/preview paths that skip it). Nothing bakes these into SSR HTML, so a
+   * consumer must render nothing rather than a zero while they are `undefined`.
+   */
+  viewCount: number | undefined;
+  commentCount: number | undefined;
+  toggleLike: (pointerEvent?: PointerEvent) => Promise<void>;
+  /**
+   * The same like state, live: updated synchronously, while the fields above update in a
+   * transition. Stable identity — publish it on the context value as is.
+   */
+  liveLikes: LiveLikes;
+}
+/** What `LiveLikes` reports — the `PostLikes` fields a widget renders. */
+type LiveLikeSnapshot = Pick<PostLikes, 'isLiked' | 'likeCount' | 'isLikeCountLoaded' | 'viewCount' | 'commentCount'>;
+/**
+ * Why the like state exists twice: on a hydrating post page, a provider state update that is
+ * NOT a transition makes React discard the server HTML of every child boundary still waiting
+ * on its module load or the viewport gate (React #421 — thunderbolt logs "SSR HTML discard").
+ * So the provider's own state updates only in transitions — but a transition is held until
+ * every boundary below has hydrated, which for a viewport-gated one means until the visitor
+ * scrolls to it. The Counters and Actions widgets subscribe here instead, after their own
+ * mount, and show the fresh numbers right away (`usePostWidgetContext`).
+ */
+interface LiveLikes {
+  get(): LiveLikeSnapshot;
+  subscribe(listener: () => void): () => void;
+}
+//#endregion
+//#region src/extensions/post-item-context-provider/post-item-context-provider.d.ts
+/**
+ * The context value IS the item — its `item*` keys sit top-level because the runtime
+ * resolves an element's binding by looking the manifest item key up on this hook's
+ * return value (through `contextSpecifier.hook`).
+ */
+type PostItemContextType = PostListItem & Omit<PostLikes, 'likeCount' | 'viewCount' | 'commentCount'> & {
+  /**
+   * The raw counters for widgets (Counters reads `likeCountValue`). Named apart
+   * from the bindable richText labels `likeCount` / `viewCount` / `commentCount`, which
+   * `PostListItem` already carries and this provider overrides once the per-cell metadata
+   * read resolves.
+   */
+  likeCountValue: number;
+  viewCountValue: number | undefined;
+  commentCountValue: number | undefined;
+  likeCount: RichText;
+  viewCount: RichText;
+  commentCount: RichText;
+};
+/**
+ * Nullable rather than throwing: the hook runs for every element inside the repeater
+ * cell, including on the editor stage before the cell is populated.
+ */
+declare function usePostItemContext(): PostItemContextType | null;
+/** Props accepted by {@link PostItemContextProvider}. */
+interface PostItemContextProviderProps extends React.PropsWithChildren {
+  /**
+   * The current item of the `postsList` array, injected by the platform per repeater
+   * cell (the Post List manifest's `contextImplementor.propKey`). Absent on the editor's
+   * unbound template cell — the three-way branch below matches the bookings builder's
+   * service-context: item → publish it; no item → render children over nulls (the
+   * nullable hook is the "null fields"); this provider has no standalone fetch path.
+   */
+  postData?: PostListItem;
+}
+/** Supplies one blog post, injected per repeater cell, to its children. */
+declare function PostItemContextProvider({
+  postData,
+  children
+}: PostItemContextProviderProps): React.ReactNode;
+//#endregion
+export { PostItemContextProvider, PostItemContextProvider as default, PostItemContextProviderProps, PostItemContextType, type PostListItem, usePostItemContext };