@adrienlcp/browser
Browser calls that hide a trap: a clipboard copy that works over plain HTTP, a link handed to the share sheet, a wake lock that survives the tab going away, the reduced-motion preference, a duration token read in seconds, a media query followed as the screen changes
Works with
- TypeScript
- Reactoptional peer
Install
pnpm add @adrienlcp/browserExports
Grouped by the section of the documentation that explains them. A row leads to its section.
Copying to the clipboard2 exports
Handing a link to the share sheet2 exports
Reduced motion1 export
Reading a duration token1 export
Reloading the page1 export
Keeping the screen awake1 export
Following a media query1 export
Documented in the source only1 export
Documentation
The README and the documents beside it, as written in the repository.
OverviewREADME.md
Small browser calls that each hide a trap. Every call the browser can refuse
returns a Result
instead of throwing.
pnpm add @adrienlcp/browserCopying to the clipboardREADME.md
import { copyText, selectContents } from '@adrienlcp/browser'
const copied = await copyText(email) // Result<void, 'refused'>
if (copied.status === 'failure') {
selectContents(emailElement) // Result<void, 'unavailable'>
}navigator.clipboard exists only in a secure context. A page served over
plain HTTP — a LAN address, a phone pointed at a laptop — has none, so
copyText falls back to selecting a hidden textarea and running
execCommand('copy'). When both are refused, selectContents leaves the text
selected for the reader to copy by hand.
Handing a link to the share sheetREADME.md
import { canShareLinks, shareLink } from '@adrienlcp/browser'
if (canShareLinks()) {
const shared = await shareLink({ title, url }) // Result<void, 'closed' | 'unavailable'>
}Phones have a share sheet and most desktops do not, so draw the control only
where canShareLinks() says so. navigator.share rejects when the sheet is
put away; that comes back as 'closed', which means nothing was sent and is
not an error worth showing.
Reduced motionREADME.md
import { prefersReducedMotion } from '@adrienlcp/browser'
element.scrollIntoView({ behavior: prefersReducedMotion() ? 'instant' : 'smooth' })false where there is no matchMedia, as on a server.
Reading a duration tokenREADME.md
import { readDurationSeconds } from '@adrienlcp/browser'
const turn = readDurationSeconds(figure, '--turn') // 0.25
figure.animate(keyframes, { duration: turn * 1000 })A script that times a motion reads the token the stylesheet holds instead of
a copy of it. Register the property as a <time>:
@property --turn
syntax: '<time>'
inherits: true
initial-value: 0sRegistered, the browser computes it to one duration whatever calc() or
var() wrote it, so a token reduced-motion.css collapses to 0ms reaches
the script as 0. Unregistered, getComputedStyle hands back the text as
written. An unset property, or one that does not read as a duration, is 0.
Reloading the pageREADME.md
import { reloadPage } from '@adrienlcp/browser'
<Button onPress={reloadPage}>Reload</Button>Does nothing where there is no location, as on a server.
Keeping the screen awakeREADME.md
import { useScreenAwake } from '@adrienlcp/browser/react'
const Countdown = ({ isRunning }: { isRunning: boolean }) => {
useScreenAwake(isRunning)
// …
}useScreenAwake(isWanted) holds the screen awake while isWanted is true and
the component is mounted. A browser releases a wake lock whenever the tab is
hidden and never takes it back; this takes it again every time the tab
returns. Where there is no Wake Lock API — before Safari 16.4, or outside a
secure context — it does nothing, and a request refused later — a phone low on
battery may refuse or revoke one at any moment — is retried on the next return
rather than reported.
Playing audio does not keep a screen awake: Chromium's media wake lock needs a video track.
Following a media queryREADME.md
import { useMediaQuery } from '@adrienlcp/browser/react'
const Menu = () => {
const isWide = useMediaQuery('(width >= 56.25rem)')
// …
}useMediaQuery(query) answers whether the screen matches query and renders
again when that changes — a window resized, a phone turned. It is false on the
server and through hydration, whose markup must match the server's: a
component with a wide and a narrow face renders the narrow one first there.
Write the query in rem, as the stylesheets' breakpoint is, so a raised font
size reaches both at the same width.
React is an optional peer dependency, needed only for these hooks.