{"slug":"share-link","name":"ShareLink","packageName":"@liquidify/react","category":"controls","maturity":"experimental","summary":"A user-invokable control that shares content — the SwiftUI ShareLink.","importPath":"@liquidify/react/share-link","sourcePath":"packages/@liquidify/react/src/components/share-link/share-link.tsx","specPath":"packages/@liquidify/react/src/components/share-link/spec.md","docsPath":"../liquidify-page/content/component-source/share-link.md","documentationStatus":"draft","storyIds":["controls-share-link--default"],"additionalExports":["ButtonSize","ButtonVariant","LiquidColor"],"anatomy":[{"name":"Glass surface (the composed Button's four-layer engine, via Link).","description":"Glass surface (the composed Button's four-layer engine, via Link)."},{"name":"Content slot","description":"Content slot — the default label is the share Icon glyph (leadingIcon)"},{"name":"Focus ring (the composed Button's CSS outline, via Link).","description":"Focus ring (the composed Button's CSS outline, via Link)."}],"props":[{"name":"aria-label","type":"string | undefined","required":false,"description":"Accessible name override — required when {@link children} is icon-only.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"children","type":"ReactNode","required":false,"description":"Custom label. Omit for the default — the \"Share\" text preceded by the `share` {@link Icon} glyph, matching SwiftUI's default `ShareLink` label. Omit alongside a {@link leadingIcon} / {@link trailingIcon} for an icon-only trigger (supply an `aria-label` in that case). children role: `label` (token parity — ShareLink's text renders through Button, via Link; no `labelProps` seam, per ADR-0028 rule 3 / charter §2 rule 5).","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"className","type":"string | undefined","required":false,"description":"Optional additional CSS class merged into the glass surface class. The supported per-instance customisation seam: override any `--lq-*` custom property from this class's CSS — the token cascade the engine reads (ADR-0004). No raw inline style is involved, so this stays ADR-0003 clean.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"disabled","type":"boolean | undefined","required":false,"description":"Disables the control, delegated to {@link Link}.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"item","type":"string","required":true,"description":"The content to share — SwiftUI `ShareLink(item:)`. A value that parses as an absolute URL is shared as the payload's `url`; anything else as its `text`. Required: a ShareLink with nothing to share has no meaning.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"leadingIcon","type":"ReactNode","required":false,"description":"Leading glyph, forwarded to {@link Link}. Supplying either icon slot suppresses the default `share` glyph so the consumer's icon stands alone.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"message","type":"string | undefined","required":false,"description":"Optional accompanying message — SwiftUI `ShareLink(message:)`. Maps to the Web Share payload's `text`, shown alongside a shared `url`.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"onClick","type":"((event: MouseEvent<HTMLButtonElement>) => void) | undefined","required":false,"description":"Low-level native passthrough; prefer `onPress`. Fires FIRST — call `event.preventDefault()` here to suppress `onPress` **and** the share invocation (charter §1 rules 2–3).","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"onError","type":"((error: unknown) => void) | undefined","required":false,"description":"Called when the native share sheet rejects for a reason other than the user cancelling it (`AbortError`, which is always swallowed silently, as on iOS). Web Share can reject for e.g. a malformed payload or a permissions failure; without a handler the failure is handed to {@link globalThis.reportError} as a documented fallback — surfacing to the global error-reporting path (`window.onerror` / devtools) rather than being silently lost.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"onPress","type":"(() => void) | undefined","required":false,"description":"Semantic activation — SwiftUI's share action closure, payload-free and fired at most once per interaction (charter §1 rule 1). Fires AFTER the {@link onClick} escape hatch when it did not cancel, and immediately before the Web Share invocation. Disabled emits nothing.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"onShare","type":"((item: string) => void) | undefined","required":false,"description":"Called with {@link item} after a successful native share, AND as the fallback when the Web Share API is unavailable — the consumer's hook to copy to the clipboard, open a custom menu, or record analytics. Not called when the user cancels the native sheet. A *completion* callback, not activation — unchanged by the `onPress` addition (charter §1).","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"ref","type":"Ref<HTMLButtonElement> | undefined","required":false,"description":"Forwarded ref to the rendered element — the component's native root (or the merged child element on a component that opts into {@link SlottableProps}). Generic over `E` (charter `docs/api-conventions.md` §4 rule 1, default `HTMLElement`) so a component with a polymorphic root (Link's navigation / action mode union, Text's `as`) can instantiate the concrete element per variant instead of leaving every consumer with a widened `Ref<HTMLElement>`. A component that does not narrow simply inherits the `HTMLElement` default — source-compatible with every pre-existing non-generic `extends ControlProps`.","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"size","type":"ButtonSize | undefined","required":false,"description":"Control size, delegated to {@link Link} — narrows the inherited {@link SizedControlProps} `size` axis to the three sizes the glass surface ships.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"subject","type":"string | undefined","required":false,"description":"Optional share title — SwiftUI `ShareLink(subject:)`. Maps to the Web Share payload's `title` (e.g. the pre-filled subject line of an email share).","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"tint","type":"LiquidTintValue | undefined","required":false,"description":"System-accent of the control — drawn from the RESTRICTED {@link LIQUID_COLORS} palette (the thirteen Apple system colours). **Orthogonal to a component's `variant`**: it recolours the accent the surface draws from (focus ring, tinted fill, selection) without changing its variant. Resolved via `data-tint` attribute selectors in CSS (tokens-only, ADR-0003).","declaredIn":"packages/@liquidify/react/src/liquid-component-props.ts"},{"name":"trailingIcon","type":"ReactNode","required":false,"description":"Trailing glyph, forwarded to {@link Link}.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"},{"name":"variant","type":"ButtonVariant | undefined","required":false,"description":"Glass style, delegated to {@link Link}. Defaults to `\"automatic\"`.","declaredIn":"packages/@liquidify/react/src/components/share-link/share-link.tsx"}],"swiftUIMap":[{"swiftUI":"`ShareLink(item:)`","react":"`item` (required)","notes":"A value that parses as an absolute URL → payload `url`; anything else → payload `text`. A ShareLink with nothing to share has no meaning.","relationship":"direct"},{"swiftUI":"`ShareLink(subject:)`","react":"`subject`","notes":"→ payload `title` (e.g. the pre-filled subject line of an email share).","relationship":"direct"},{"swiftUI":"`ShareLink(message:)`","react":"`message`","notes":"→ payload `text`. Appended to a non-URL `item` (`\"{message}\\n\\n{item}\"`) rather than overwriting it — the required `item` content never vanishes from the share sheet.","relationship":"direct"},{"swiftUI":"`ShareLink { label }`","react":"`children` (node) + `leadingIcon` / `trailingIcon`","notes":"children role: `label` (token parity — ShareLink's text renders through Button; no `labelProps` seam, ADR-0028 rule 3 / charter §2 rule 5). Omit for the default \"Share\" + share-glyph label.","relationship":"direct"},{"swiftUI":"`.buttonStyle(_:)`","react":"`variant`","notes":"`ButtonVariant`, forwarded to Button.","relationship":"direct"},{"swiftUI":"`.controlSize(_:)`","react":"`size`","notes":"`small | regular | large`, the truthful `ButtonSize` re-export (charter §7 rule 4, composition-wrapper exception).","relationship":"direct"},{"swiftUI":"`.tint(color)`","react":"`tint`","notes":"Restricted `LiquidColor` palette; recolours the prominent/translucent surfaces only.","relationship":"direct"},{"swiftUI":"`.disabled(_:)`","react":"`disabled`","notes":"Shape N: native `<button disabled>`, no `aria-disabled` (the composed Link always renders its action-mode button here).","relationship":"direct"},{"swiftUI":"Share action closure","react":"`onPress?: () => void`","notes":"Payload-free semantic activation (charter §1 rule 1) — fires at invocation, at most once per interaction. Fires after `onClick` when it did not cancel. Disabled emits nothing.","relationship":"direct"},{"swiftUI":"*(web-only)*","react":"`onClick?: (event: MouseEvent<HTMLButtonElement>) => void`","notes":"Low-level native passthrough; prefer `onPress`. Fires FIRST; `event.preventDefault()` suppresses `onPress` **and** the share invocation (charter §1 rules 2–3).","relationship":"web-only"},{"swiftUI":"Completion (no SwiftUI analogue — `ShareLink` has no completion handler)","react":"`onShare?: (item: string) => void`","notes":"Fires after a successful native share, OR as the fallback when `navigator.share` is unavailable. Not called on a user-cancelled share (`AbortError`). *Unchanged by this pass — stays a completion callback, not activation (charter §1).*","relationship":"web-only"},{"swiftUI":"*(web-only)*","react":"`onError?: (error: unknown) => void`","notes":"Non-`AbortError` rejections. Absent handler ⇒ handed to `globalThis.reportError` (documented fallback).","relationship":"web-only"}],"tokens":["--lq-button-fill","--lq-button-label","--lq-button-ring","--lq-tint-current"],"keyboard":[{"key":"Keyboard","action":"Space / Enter activates (the composed 's native handling); Tab focuses."}],"variants":["automatic","bordered","borderedProminent","borderless","glass","glassProminent","plain","translucent"],"variantPages":[]}