Skip to main content

Web Share

import * as mod from "jsr:@nzip/lofi/recipes/web-share";

Opt-in helpers for outbound Web Share and inbound text/link share targets.

The helpers feature-detect browser support and parse received values without mutating application data. Add the matching manifest member and receiver UI only when the product has a concrete sharing workflow.

parseTextShareTarget​

function

function parseTextShareTarget(input: URL | URLSearchParams | string, options: ParseTextShareTargetOptions): TextShareTargetResult

Parse an inbound GET share target as an untrusted draft.

Unknown parameters are ignored. Duplicate, oversized, malformed, and non-HTTP(S) values reject the whole draft. The caller must still present the returned draft for explicit user confirmation before persisting anything.

shareOrFallback​

function

async function shareOrFallback(data: WebShareData, options: ShareOrFallbackOptions): Promise<WebShareOutcome>

Attempt a user-triggered native share and use a normal web fallback only when the capability is unavailable or rejects the payload up front.

Call this function directly from a click/submit handler: browsers require transient user activation for navigator.share(). A runtime share failure is reported as failed so callers can offer a retry or explicit copy action without unexpectedly copying data after the native sheet opened.

TEXT_SHARE_LIMITS​

const

const TEXT_SHARE_LIMITS: Readonly<TextShareTargetLimits>;

Default limits for the text/link share-target recipe.

ParseTextShareTargetOptions​

type

type ParseTextShareTargetOptions = {
  names?: Partial<TextShareTargetNames>;
  limits?: Partial<TextShareTargetLimits>;
};

Optional manifest-name and input-limit overrides for the inbound parser.

ShareOrFallbackOptions​

type

type ShareOrFallbackOptions = {
  client?: WebShareClient;
  fallback: (data: WebShareData) => void | Promise<void>;
};

Browser seam and fallback used for one outbound share attempt.

TextShareTargetDraft​

type

type TextShareTargetDraft = {
  title?: string;
  text?: string;
  url?: string;
};

Parsed text/link values awaiting explicit user confirmation.

TextShareTargetIssue​

type

type TextShareTargetIssue = 
  | "duplicate-title"
  | "duplicate-text"
  | "duplicate-url"
  | "title-too-long"
  | "text-too-long"
  | "url-too-long"
  | "invalid-url"
  | "unsupported-url-protocol"
  | "empty-share";

Stable validation issue that never contains received share values.

TextShareTargetLimits​

type

type TextShareTargetLimits = {
  title: number;
  text: number;
  url: number;
};

Length limits applied to received title, text, and URL values.

TextShareTargetNames​

type

type TextShareTargetNames = {
  title: string;
  text: string;
  url: string;
};

Query-parameter names declared by the matching manifest share target.

TextShareTargetResult​

type

type TextShareTargetResult = { ok: true; draft: TextShareTargetDraft; issues: readonly [] } | { ok: false; issues: readonly TextShareTargetIssue[] };

Accepted draft or value-free rejection from an inbound share target.

WebShareClient​

type

type WebShareClient = {
  canShare?: (data: WebShareData) => boolean;
  share?: (data: WebShareData) => Promise<void>;
};

Minimal browser seam used by shareOrFallback.

WebShareData​

type

type WebShareData = {
  title?: string;
  text?: string;
  url?: string;
  files?: readonly File[];
};

Data accepted by the browser Web Share API.

WebShareOutcome​

type

type WebShareOutcome = 
  | "shared"
  | "cancelled"
  | "fallback"
  | "failed";

Stable, value-free outcome from one outbound share attempt.