spoiler-ui 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dzmitry
+
+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

@@ -0,0 +1,576 @@
+# spoiler-ui
+
+A lightweight, zero-dependency spoiler / content-reveal element — like **Threads**, **Discord**, and **Telegram**.
+
+Blurs hidden content behind a pill overlay. Click (or press Enter / Space) to reveal with a smooth transition.
+
+**MIT license · zero dependencies · Vanilla JS + optional React wrapper · TypeScript types included**
+
+<!-- SCREENSHOT: demo of all three modes (idle blurred, loading, revealed) -->
+
+---
+
+## Install
+
+```bash
+npm install spoiler-ui
+```
+
+---
+
+## Three modes
+
+| Mode | Content in DOM before reveal? | Requires server? |
+|------|-------------------------------|-----------------|
+| [UI only](#mode-1--ui-only) | Yes, blurred | No |
+| [UI + encoding](#mode-3--ui--encoding) | Yes, as Base64 | No |
+| [UI + backend](#mode-2--ui--backend) | No | Yes |
+
+---
+
+## Mode 1 — UI only
+
+The simplest mode. Content is blurred in the DOM; revealing is purely client-side. A determined user can find the text in DevTools, but it stops casual glances.
+
+### Vanilla JS
+
+```js
+import { createSpoiler, initSpoilers } from 'spoiler-ui';
+import 'spoiler-ui/style';
+
+// Programmatic
+const spoiler = createSpoiler('Snape kills Dumbledore.', {
+  label: 'Book spoiler',
+});
+document.querySelector('p').appendChild(spoiler);
+
+// Custom label, button-only reveal
+const strictSpoiler = createSpoiler('He was dead the whole time.', {
+  label: 'Major spoiler',
+  revealOnClick: false,   // only the pill button reveals, not the whole element
+  blurAmount: 10,
+  animationDuration: 500,
+  onReveal: (text) => console.log('Revealed:', text),
+  onError: (err) => console.error('Failed:', err),
+});
+document.body.appendChild(strictSpoiler);
+```
+
+**Auto-init from HTML attributes** — no JS needed per element:
+
+```html
+<script type="module">
+  import { initSpoilers } from 'spoiler-ui';
+  import 'spoiler-ui/style';
+  initSpoilers();
+</script>
+
+<!-- Basic -->
+<span data-spoiler>Jon Snow is resurrected.</span>
+
+<!-- Custom label, blur, and icon -->
+<span data-spoiler="Huge spoiler" data-spoiler-blur="10" data-spoiler-icon="🔒">
+  The planet explodes at the end.
+</span>
+
+<!-- Extra CSS class for custom theming -->
+<span data-spoiler="Spoiler" data-spoiler-class="my-theme">
+  The twist is revealed in chapter 12.
+</span>
+```
+
+### React
+
+```jsx
+import { Spoiler } from 'spoiler-ui/react';
+import 'spoiler-ui/style';
+
+export default function ReviewPost() {
+  return (
+    <p>
+      The film was stunning, but I did not expect{' '}
+      <Spoiler label="ending spoiler">
+        the hero to sacrifice herself in the final act
+      </Spoiler>
+      .
+    </p>
+  );
+}
+```
+
+With callbacks and a custom ref:
+
+```jsx
+import { useRef } from 'react';
+import { Spoiler } from 'spoiler-ui/react';
+
+const ref = useRef(null);
+
+<Spoiler
+  ref={ref}
+  label="Major spoiler"
+  blurAmount={10}
+  revealOnClick={false}
+  animationDuration={500}
+  onReveal={(text) => analytics.track('spoiler_revealed', { text })}
+  onError={(err) => console.error('Reveal failed:', err)}
+>
+  The murderer was the detective all along.
+</Spoiler>
+```
+
+---
+
+## Mode 2 — UI + backend
+
+The text is **never sent to the browser** until the user clicks reveal. On click, the component fetches the content from your server, shows a loading indicator, then reveals. A user inspecting DevTools before clicking will find nothing.
+
+On network failure, the pill shows "Failed — retry?" and re-clicking retries the fetch automatically.
+
+### Vanilla JS
+
+```js
+import { createSpoiler } from 'spoiler-ui';
+import 'spoiler-ui/style';
+
+const spoiler = createSpoiler(null, {
+  src: '/api/spoilers/42',
+  label: 'Spoiler',
+  onReveal: (text) => console.log('Fetched and revealed:', text),
+  onError: (err) => reportError(err),
+});
+document.querySelector('.post').appendChild(spoiler);
+```
+
+With authentication headers:
+
+```js
+const spoiler = createSpoiler(null, {
+  src: '/api/spoilers/42',
+  fetchOptions: {
+    headers: { Authorization: `Bearer ${token}` },
+    credentials: 'include',
+  },
+  onReveal: (text) => markAsRead(42),
+});
+```
+
+With an optional blurred placeholder shown while loading:
+
+```js
+// 'Loading content…' is shown blurred until the fetch completes,
+// then replaced with the real server response.
+const spoiler = createSpoiler('Loading content\u2026', {
+  src: '/api/spoilers/42',
+});
+```
+
+**HTML attributes:**
+
+```html
+<span
+  data-spoiler="Spoiler"
+  data-spoiler-src="/api/spoilers/42"
+>
+</span>
+
+<!-- Server returns HTML markup -->
+<span
+  data-spoiler="Spoiler"
+  data-spoiler-src="/api/spoilers/43"
+  data-spoiler-response-type="html"
+>
+</span>
+```
+
+> **Note on `responseType: 'html'`:** The server response is injected via `innerHTML`. You are responsible for sanitising HTML before serving it. Use `responseType: 'text'` (the default) whenever the content is plain text.
+
+### React
+
+```jsx
+import { Spoiler } from 'spoiler-ui/react';
+import 'spoiler-ui/style';
+
+export default function Post({ spoilerId }) {
+  return (
+    <p>
+      The twist is{' '}
+      <Spoiler
+        src={`/api/spoilers/${spoilerId}`}
+        label="Spoiler"
+        loadingLabel="Fetching…"
+        errorLabel="Load failed — retry?"
+        onReveal={(text) => console.log('Revealed:', text)}
+        onError={(err) => reportError(err)}
+      />
+      .
+    </p>
+  );
+}
+```
+
+With auth and HTML response:
+
+```jsx
+<Spoiler
+  src="/api/spoilers/99"
+  fetchOptions={{ headers: { Authorization: `Bearer ${token}` } }}
+  responseType="html"
+  onReveal={(html) => markSpoilerSeen(99)}
+  onError={(err) => toast.error('Could not load spoiler')}
+/>
+```
+
+**State behaviour:**
+
+| State | Pill shows | Cursor |
+|-------|-----------|--------|
+| Idle | label + 👁 | pointer |
+| Loading | "Loading…" + spinner | wait |
+| Error | "Failed — retry?" + ⚠ | pointer |
+| Revealed | *(overlay removed)* | auto |
+
+---
+
+## Mode 3 — UI + encoding
+
+The content is Base64-encoded and stored in a `data-` attribute. The plaintext **never appears in the DOM** — it is decoded in memory only when the user clicks reveal, then injected and displayed. A DevTools inspection before clicking shows only the encoded payload, not readable text.
+
+> **Security note:** Base64 is obscurity, not encryption. Anyone who spots the encoded attribute can decode it in seconds with `atob()`. This is meaningfully better than plaintext for casual spoiler protection, but not suitable for genuinely sensitive data. Use [Mode 2](#mode-2--ui--backend) if the content must stay secret.
+
+### Prepare the payload
+
+Use the bundled `encodeBase64` utility anywhere that runs JS — a build script, a server, or the browser console:
+
+```js
+import { encodeBase64 } from 'spoiler-ui';
+
+const payload = encodeBase64('Darth Vader is Luke\'s father.');
+// → 'RGFydGggVmFkZXIgaXMgTHVrZSdzIGZhdGhlci4='
+
+// Full Unicode support — emoji and non-Latin scripts work fine
+encodeBase64('王子 is the killer 🗡️');
+```
+
+### Vanilla JS
+
+```js
+import { createSpoiler, encodeBase64 } from 'spoiler-ui';
+import 'spoiler-ui/style';
+
+const payload = encodeBase64('The real treasure was the friends we made along the way.');
+
+const spoiler = createSpoiler(payload, {
+  encoded: true,
+  label: 'Spoiler',
+  onReveal: (text) => console.log('Decoded and revealed:', text),
+  onError: (err) => console.error('Decode failed:', err),
+});
+document.body.appendChild(spoiler);
+```
+
+**What DevTools shows** (vanilla JS — React produces the same structure but as a React-managed DOM):
+
+```html
+<!-- Before reveal — only the encoded payload is in the DOM -->
+<span class="spoiler-ui" data-state="idle" data-revealed="false"
+      data-spoiler-payload="VGhlIHJlYWwgdHJlYXN1cmUgd2FzIHRoZSBmcmllbmRzIHdlIG1hZGUgYWxvbmcgdGhlIHdheS4=">
+  <span class="spoiler-ui__inner"></span>
+  <span class="spoiler-ui__overlay" role="button" tabindex="0" aria-label="Reveal Spoiler">
+    <span class="spoiler-ui__pill">Spoiler</span>
+  </span>
+</span>
+
+<!-- After reveal — payload attribute removed, plaintext injected -->
+<span class="spoiler-ui" data-state="revealed" data-revealed="true">
+  <span class="spoiler-ui__inner">The real treasure was the friends we made along the way.</span>
+</span>
+```
+
+**HTML attributes:**
+
+Encode your content and embed it in `data-spoiler-encoded`:
+
+```html
+<span
+  data-spoiler="Spoiler"
+  data-spoiler-encoded="VGhlIHJlYWwgdHJlYXN1cmUgd2FzIHRoZSBmcmllbmRzIHdlIG1hZGUgYWxvbmcgdGhlIHdheS4="
+>
+</span>
+```
+
+```js
+import { initSpoilers } from 'spoiler-ui';
+initSpoilers();
+```
+
+### React
+
+Pass the Base64 string as `children` and set `encoded`:
+
+```jsx
+import { Spoiler } from 'spoiler-ui/react';
+import 'spoiler-ui/style';
+
+// Payload prepared at build time or server-side
+const PAYLOAD = 'RGFydGggVmFkZXIgaXMgTHVrZSdzIGZhdGhlci4=';
+
+export default function FilmReview() {
+  return (
+    <p>
+      The most iconic twist in cinema history:{' '}
+      <Spoiler encoded onReveal={(text) => console.log(text)}>
+        {PAYLOAD}
+      </Spoiler>
+      .
+    </p>
+  );
+}
+```
+
+---
+
+## Theming
+
+Override CSS variables on `.spoiler-ui` or any ancestor to retheme without touching the stylesheet.
+
+### Stylesheet
+
+```css
+.spoiler-ui {
+  --spoiler-pill-bg: #6366f1;
+  --spoiler-pill-color: #fff;
+  --spoiler-bg: rgba(99, 102, 241, 0.1);
+}
+```
+
+### React — per-instance via `style` prop
+
+```jsx
+<Spoiler
+  label="Critical"
+  style={{
+    '--spoiler-pill-bg': '#e11d48',
+    '--spoiler-pill-color': '#fff',
+    '--spoiler-bg': 'rgba(225, 29, 72, 0.08)',
+  }}
+>
+  CVE-2024-1234 — remote code execution on /api/upload
+</Spoiler>
+```
+
+### `renderPill` — full pill customisation (React)
+
+```jsx
+<Spoiler
+  label="Reveal lineage"
+  renderPill={({ state, label }) => (
+    <span style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+      {state === 'idle' ? '🌑' : state === 'loading' ? '⏳' : '⚠️'}
+      <em>{label}</em>
+    </span>
+  )}
+>
+  Luke, I am your father.
+</Spoiler>
+```
+
+---
+
+## API reference
+
+### `createSpoiler(content, options?)`
+
+```js
+import { createSpoiler } from 'spoiler-ui';
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `content` | `string \| Element \| null` | Content to hide. Pass `null` when using `src` or `encoded`. |
+| `options.label` | `string` | Pill text. Default: `'Spoiler'` |
+| `options.blurAmount` | `number` | Blur in px while hidden. Default: `6` |
+| `options.revealOnClick` | `boolean` | Click anywhere on element to reveal. Default: `true` |
+| `options.animationDuration` | `number` | Transition in ms. Default: `300` |
+| `options.className` | `string` | Extra class on root element. Default: `''` |
+| `options.src` | `string` | URL to fetch content from on reveal. |
+| `options.fetchOptions` | `RequestInit` | Passed directly to `fetch()`. Default: `{}` |
+| `options.responseType` | `'text' \| 'html'` | How to inject fetched/decoded content. Default: `'text'` |
+| `options.encoded` | `boolean` | Treat `content` as Base64; decode on reveal. Default: `false` |
+| `options.icon` | `string \| false \| null` | Override the pill icon. String replaces the default 👁; `false`/`null` hides it entirely. Default: uses `--spoiler-icon` CSS variable. |
+| `options.showPill` | `boolean` | Show the pill label button. Default: `true` |
+| `options.loadingLabel` | `string` | Pill text while fetching. Default: `'Loading…'` |
+| `options.errorLabel` | `string` | Pill text on fetch/decode failure. Default: `'Failed — retry?'` |
+| `options.onReveal` | `(content: string) => void` | Called after successful reveal with the revealed text. |
+| `options.onError` | `(err: Error) => void` | Called when a fetch or Base64 decode fails. |
+
+Returns an `HTMLElement` ready to insert into the DOM.
+
+---
+
+### `initSpoilers(scope?)`
+
+```js
+import { initSpoilers } from 'spoiler-ui';
+```
+
+Scans `scope` (default: `document`) for `[data-spoiler]` elements and converts them.
+
+**Supported HTML attributes:**
+
+| Attribute | Corresponds to |
+|-----------|---------------|
+| `data-spoiler` | `label` (required to activate) |
+| `data-spoiler-blur` | `blurAmount` |
+| `data-spoiler-duration` | `animationDuration` |
+| `data-spoiler-reveal-on-click` | `revealOnClick` — set to `'false'` to restrict reveal to the pill button only |
+| `data-spoiler-show-pill` | `showPill` — set to `'false'` to hide the pill label button |
+| `data-spoiler-loading-label` | `loadingLabel` — pill text while fetching |
+| `data-spoiler-error-label` | `errorLabel` — pill text on failure |
+| `data-spoiler-src` | `src` |
+| `data-spoiler-response-type` | `responseType` (`'text'` or `'html'`) |
+| `data-spoiler-encoded` | Base64 payload; enables `encoded` mode |
+| `data-spoiler-class` | `className` — extra CSS class on the root element |
+| `data-spoiler-icon` | `icon` — `'false'` hides the icon; any other string replaces the default 👁 |
+
+> `onReveal`, `onError`, and `fetchOptions` cannot be set via HTML attributes — use `createSpoiler()` or the React `<Spoiler>` component for callbacks and custom fetch configuration.
+
+---
+
+### `<Spoiler>` (React)
+
+```js
+import { Spoiler } from 'spoiler-ui/react';
+```
+
+Accepts the same options as `createSpoiler` as props, plus `children` in place of the `content` parameter.
+
+| Prop | Type | Default |
+|------|------|---------|
+| `children` | `ReactNode` | — |
+| `label` | `string` | `'Spoiler'` |
+| `blurAmount` | `number` | `6` |
+| `revealOnClick` | `boolean` | `true` |
+| `animationDuration` | `number` | `300` |
+| `className` | `string` | `''` |
+| `src` | `string` | — |
+| `fetchOptions` | `RequestInit` | `{}` |
+| `responseType` | `'text' \| 'html'` | `'text'` |
+| `encoded` | `boolean` | `false` |
+| `icon` | `string \| false \| null` | CSS `--spoiler-icon` (👁 by default) |
+| `showPill` | `boolean` | `true` |
+| `loadingLabel` | `string` | `'Loading…'` |
+| `errorLabel` | `string` | `'Failed — retry?'` |
+| `renderPill` | `(ctx: { state, label }) => ReactNode` | Render prop for full pill customisation. |
+| `onReveal` | `(content?: string) => void` | Called after successful reveal. |
+| `onError` | `(err: Error) => void` | Called when a fetch or decode fails. |
+| `style` | `CSSProperties & { [key: \`--${string}\`]: string }` | Inline styles merged onto root. Use to override CSS variables per instance. |
+| `ref` | `RefObject<HTMLSpanElement>` | Forwarded to the root `<span>` via `forwardRef`. |
+
+---
+
+### `encodeBase64(str)` / `decodeBase64(b64)`
+
+```js
+import { encodeBase64, decodeBase64 } from 'spoiler-ui';
+```
+
+Full Unicode support via `TextEncoder` / `TextDecoder`. Use `encodeBase64` at build time or server-side to prepare payloads for encoded mode.
+
+```js
+const payload = encodeBase64('Snape kills Dumbledore.');
+// → 'U25hcGUga2lsbHMgRHVtYmxlZG9yZS4='
+
+decodeBase64('U25hcGUga2lsbHMgRHVtYmxlZG9yZS4=');
+// → 'Snape kills Dumbledore.'
+```
+
+---
+
+## CSS customisation
+
+Import the stylesheet and override variables on `.spoiler-ui` or any parent:
+
+```js
+import 'spoiler-ui/style';
+```
+
+```css
+.spoiler-ui {
+  --spoiler-blur: 8px;            /* blur amount while hidden */
+  --spoiler-duration: 400ms;      /* reveal transition speed */
+  --spoiler-bg: rgba(0,0,0,0.2);  /* overlay background */
+  --spoiler-pill-bg: #1a1a2e;     /* pill background (idle) */
+  --spoiler-pill-color: #e0e0ff;  /* pill text colour */
+  --spoiler-pill-font: inherit;   /* pill font family */
+  --spoiler-radius: 6px;          /* corner radius on overlay */
+  --spoiler-error-bg: #c0392b;    /* pill background on error */
+  --spoiler-icon: '🔒';           /* icon shown before pill text */
+  --spoiler-pill-padding: 1px 8px;
+  --spoiler-pill-font-size: 0.72em;
+  --spoiler-pill-font-weight: 600;
+  --spoiler-pill-letter-spacing: 0.02em;
+  --spoiler-pill-gap: 4px;             /* gap between icon and label */
+  --spoiler-pill-radius: 100px;        /* pill border radius */
+  --spoiler-shimmer-color: rgba(255,255,255,0.5);
+  --spoiler-shimmer-duration: 2.4s;
+}
+```
+
+Dark mode is **not** applied automatically — override the variables in your own stylesheet:
+
+```css
+@media (prefers-color-scheme: dark) {
+  .spoiler-ui {
+    --spoiler-bg: rgba(255, 255, 255, 0.08);
+    --spoiler-pill-bg: rgba(255, 255, 255, 0.18);
+    --spoiler-pill-color: #fff;
+    --spoiler-error-bg: #e74c3c;
+  }
+}
+```
+
+Animations are disabled automatically via `@media (prefers-reduced-motion: reduce)`.
+
+### Custom overlay animation
+
+The overlay is `.spoiler-ui__overlay`. Target it directly to replace or extend the built-in shimmer:
+
+```css
+/* Disable default shimmer */
+.spoiler-ui {
+  --spoiler-shimmer-color: transparent;
+}
+
+/* Add your own animation */
+.spoiler-ui__overlay::before {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  background-image: url('noise.png');
+  animation: my-particles 3s linear infinite;
+}
+
+@keyframes my-particles {
+  to { background-position: 200px 200px; }
+}
+```
+
+The overlay switches to `opacity: 0; pointer-events: none` on reveal — your custom animation cleans up automatically.
+
+---
+
+## Accessibility
+
+- The reveal button has `role="button"`, `tabindex="0"`, and `aria-label="Reveal {label}"`.
+- `aria-expanded="false"` is set while hidden; the attribute is removed after reveal.
+- Keyboard: `Enter` or `Space` to reveal — works regardless of `revealOnClick`.
+- After reveal the overlay is removed from tab order and marked `aria-hidden`.
+- Focus ring shown via `:focus-visible` (no ring on mouse click).
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "spoiler-ui",
+  "version": "1.0.0",
+  "description": "Lightweight spoiler/content-reveal UI element — like Threads & Discord. Vanilla JS + optional React wrapper.",
+  "keywords": ["spoiler", "ui", "reveal", "blur", "discord", "threads", "component"],
+  "author": "Dzmitry Ihnatovich",
+  "license": "MIT",
+  "type": "module",
+  "types": "./spoiler.d.ts",
+  "main": "./spoiler.js",
+  "module": "./spoiler.js",
+  "exports": {
+    ".": {
+      "import": "./spoiler.js",
+      "types": "./spoiler.d.ts"
+    },
+    "./react": {
+      "import": "./react.jsx",
+      "types": "./react.d.ts"
+    },
+    "./style": {
+      "import": "./spoiler.css",
+      "types": "./style.d.ts"
+    }
+  },
+  "files": [
+    "spoiler.js",
+    "spoiler.d.ts",
+    "react.jsx",
+    "react.d.ts",
+    "spoiler.css",
+    "style.d.ts",
+    "README.md"
+  ],
+  "sideEffects": [
+    "./spoiler.css"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true },
+    "react-dom": { "optional": true }
+  },
+  "devDependencies": {
+    "vite": "^5.0.0"
+  },
+  "scripts": {
+    "dev": "vite demo",
+    "build": "vite build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/guestDI/spoiler-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/guestDI/spoiler-ui/issues"
+  },
+  "homepage": "https://github.com/guestDI/spoiler-ui#readme"
+}