@tokshare/pick 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Torki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @tokshare/pick
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let visitors send files from their phone to your website: a button, a QR code, and ordinary `File`
+objects in your page. No app on the phone.
+
+## Upload field (recommended)
+
+A complete upload field: drop zone, **Browse files**, and **Use your phone**, which opens inside the
+field (QR code, steps, live status). Files from the computer and the phone land in one list with
+thumbnails and remove buttons, and in a real `<input type="file" name>` so your form submits them.
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@tokshare/pick/dist/picker.global.js" data-key="pk_live_…" defer></script>
+
+<form method="post" enctype="multipart/form-data">
+  <tokshare-pick-field name="photos" accept="image/png,image/jpeg" max-size="5MB" max-files="6" multiple></tokshare-pick-field>
+  <button>Publish</button>
+</form>
+```
+
+Attributes: `name`, `accept`, `multiple`, `max-files`, `max-size` (`5MB`, `500KB`), `resize` (longest
+side in pixels for photos from the phone), `phone` (`inline`, `modal` or `off`), `locale`, `theme`,
+`label`, `key`, `relay`. The element fires a `files` event with the current `File[]`.
+
+From npm: `mountField(element, { key, name, accept, maxFileBytes, multiple })` returns
+`{ files, input, on("change"), remove(file), clear(), destroy() }`, or call `defineFieldElement({ key })`
+to register `<tokshare-pick-field>`. On a page that is itself open on a phone, "Use your phone" is
+hidden (`phoneOnMobile: true` to keep it). `theme: "auto"` matches the page behind the field.
+
+## Script tag: a button for an existing input
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@tokshare/pick/dist/picker.global.js" data-key="pk_live_…" defer></script>
+
+<input type="file" id="photos" name="photos" accept="image/*" multiple>
+<button type="button" data-tokshare-pick-for="photos">From my phone</button>
+```
+
+The button fills the input (firing `input` and `change`), so your form works unchanged. Add
+`data-mode="append"` to add to files already chosen.
+
+## npm
+
+```sh
+npm install @tokshare/pick
+```
+
+```js
+import { pick, open, attach } from "@tokshare/pick";
+
+// Promise: the files, or [] if the person cancels.
+const files = await pick({ key: "pk_live_…", accept: "image/*,.pdf", maxFiles: 5 });
+
+// Live events.
+const picker = open({ key: "pk_live_…" });
+picker.on("phone", ({ phone }) => console.log("connected", phone.label));
+picker.on("progress", ({ name, sent, total, phase }) => console.log(name, phase, sent / total));
+picker.on("file", (file) => console.log("received", file.name));
+const all = await picker.done;
+
+// Fill an existing input.
+const fromPhone = attach(document.querySelector("#avatar"), { key: "pk_live_…" });
+button.addEventListener("click", fromPhone);
+
+// Your own UI: no modal; show picker.claimUrl as a QR and picker.code as text.
+const headless = open({ key: "pk_live_…", ui: false });
+headless.on("ready", ({ claimUrl, code }) => render(claimUrl, code));
+```
+
+## React
+
+`@tokshare/pick/react` (same package, React 17+). Set the key once, then drop components in:
+
+```tsx
+import { TokShareProvider, TokSharePick, TokSharePickButton } from "@tokshare/pick/react";
+
+export default function App() {
+  return (
+    <TokShareProvider pickKey="pk_live_…">
+      <ListingForm />
+    </TokShareProvider>
+  );
+}
+
+function ListingForm() {
+  const [photos, setPhotos] = useState<File[]>([]);
+  return (
+    <form>
+      {/* The full field: drop zone, Browse files, Use your phone. `name` makes a normal submit include the files. */}
+      <TokSharePick name="photos" accept="image/png,image/jpeg" maxFiles={6} maxFileBytes="5MB" onChange={setPhotos} />
+
+      {/* Or just a button: opens the phone window, gives you File[]. Takes every <button> prop. */}
+      <TokSharePickButton accept="image/*" onFiles={(files) => setPhotos((all) => [...all, ...files])} className="btn">
+        From my phone
+      </TokSharePickButton>
+    </form>
+  );
+}
+```
+
+- `pickKey` (React reserves `key`) and `relay`, `locale`, `theme` can go on the provider, or on any component
+  instead of a provider.
+- `<TokSharePick>` takes the field's options as props: `name`, `accept`, `multiple`, `maxFiles`,
+  `maxFileBytes` (bytes or `"5MB"`), `resize` (longest side for phone photos), `phone` (`"inline"`,
+  `"modal"`, `false`), `label`, `strings`, plus `className`, `style`, `onChange(files)`. A ref gives
+  `files`, `input`, `remove(file)` and `clear()`. Changing an option rebuilds the field.
+- Your own trigger: `const { pick, open } = useTokSharePick({ accept: "image/*" })`, then
+  `const files = await pick()` in a click handler (`[]` if the person cancels).
+- Next.js: the components are client components (`"use client"` is built in); import them anywhere.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `key` | — | Your publishable key, bound to your site's origins. |
+| `accept` | any | Like `<input accept>`: `"image/*,.pdf"`. Checked on the phone and on the relay, including the file's real type. |
+| `multiple` | `true` | `false` for a single file. |
+| `maxFiles` | 20 | Up to the plan's limit. |
+| `maxFileBytes` | 50 MB | Up to the plan's limit. |
+| `resizeImages` | off | `{ maxDimension: 1600, quality: 0.82 }` shrinks photos on the phone. |
+| `confirmPhone` | `false` | Someone at the computer approves the phone (both show the same number). |
+| `siteName` | your host | Shown on the phone: "*siteName* is asking for files". |
+| `direct` | `true` | When the phone is on the same Wi-Fi as the computer, files go straight to the page over the local network (WebRTC) instead of the cloud: seconds instead of minutes on a slow internet upload. Falls back to the cloud by itself. `false` always uses the cloud. Field attribute `direct="off"`, script tag `data-direct="off"`. |
+| `announce` | `true` | A small line about TokShare for desktop under the phone QR, which visitors can hide. `false` removes it. Field attribute `announce="off"`, script tag `data-announce="off"`. |
+| `locale` | `"auto"` | `"en"` or `"ar"` (right to left). Auto follows `<html lang>`, then the browser. |
+| `theme` | `"auto"` | `"light"`, `"dark"` or `"auto"`. |
+| `strings` | — | Replace any modal text. |
+| `relay` | hosted | Your own relay URL. |
+| `signal` | — | An `AbortSignal` that cancels the picker. |
+
+### Direct transfers (same Wi-Fi)
+
+The phone and the page set up a WebRTC data channel through the relay. No STUN or TURN servers are
+used, so only local-network addresses (which browsers hide behind random `.local` names) can connect:
+it works on the same network and nowhere else, and neither side learns the other's public IP. The
+relay still approves every file first (count, size, type, usage), and the page checks what arrives
+exactly as the relay checks a cloud upload: the announced size, and contents that match `accept`.
+If the link isn't there or drops mid-file, that file goes through the cloud under the same id. The
+`direct` event (`{ connected }`) and "Connected over Wi-Fi" in the built-in UI show when it's on.
+
+Style the modal with CSS variables on `[data-tokshare-pick]`: `--tsp-accent`, `--tsp-accent-text`,
+`--tsp-bg`, `--tsp-text`, `--tsp-muted`, `--tsp-line`, `--tsp-radius`, `--tsp-font`.
+
+## Content-Security-Policy
+
+Add the relay to `connect-src` (HTTPS and WSS). The modal needs nothing else: it uses a Shadow DOM
+with a constructable stylesheet and draws the QR on a canvas.
+
+## Privacy
+
+Files travel from the phone to your page through TokShare's relay and are deleted as soon as your page
+receives them (at most 10 minutes after upload). Contents are never inspected beyond the first bytes
+used to check the file type, and never logged.