spoiler-ui 1.0.0

package/react.d.ts

@@ -0,0 +1,67 @@
+import type { ReactNode, ReactElement, CSSProperties, ForwardRefExoticComponent, RefAttributes } from 'react';
+
+export interface SpoilerProps {
+  /** Content to hide. Optional when `src` or `encoded` is set. */
+  children?: ReactNode;
+  label?: string;
+  blurAmount?: number;
+  revealOnClick?: boolean;
+  animationDuration?: number;
+  className?: string;
+  /**
+   * URL to fetch content from on reveal. When set, `children` is optional
+   * and is shown blurred as a placeholder until the fetch completes.
+   */
+  src?: string;
+  /** Options passed directly to `fetch()`. Default: `{}` */
+  fetchOptions?: RequestInit;
+  /**
+   * How to inject fetched content.
+   * - `'text'` (default): rendered as a text node — safe against XSS
+   * - `'html'`: rendered via `dangerouslySetInnerHTML` — XSS opt-in
+   */
+  responseType?: 'text' | 'html';
+  /**
+   * When `true`, `children` must be a Base64-encoded string. It is decoded
+   * only when the user reveals — the plaintext is never rendered beforehand.
+   *
+   * Note: Base64 is obscurity, not encryption. A determined user can still
+   * decode it from page source. Use `src` for true server-gated hiding.
+   */
+  encoded?: boolean;
+  /**
+   * Override the pill icon shown before the label.
+   * - `string` — replaces the default 👁 with the given character/emoji
+   * - `false` or `null` — hides the icon entirely
+   * - `undefined` (default) — uses the CSS `--spoiler-icon` variable (👁)
+   */
+  icon?: string | false | null;
+  /** Hide the pill label button. The overlay and shimmer still show; click still reveals. Default: `true` */
+  showPill?: boolean;
+  /** Text shown on the pill while a fetch is in progress. Default: `'Loading…'` */
+  loadingLabel?: string;
+  /** Text shown on the pill when a fetch or decode fails. Default: `'Failed — retry?'` */
+  errorLabel?: string;
+  /**
+   * Render prop for full pill customisation. Receives `{ state, label }` and returns a ReactNode.
+   * Rendered inside the existing `.spoiler-ui__pill` span, so CSS styling still applies.
+   */
+  renderPill?: (ctx: { state: 'idle' | 'loading' | 'error'; label: string }) => import('react').ReactNode;
+  /**
+   * Callback fired after a successful reveal.
+   * - Fetch mode: receives the fetched content string.
+   * - Encoded mode: receives the decoded content string.
+   * - Plain mode: called with no arguments.
+   */
+  onReveal?: (content?: string) => void;
+  /** Callback fired when a fetch or decode fails. Receives the Error object. */
+  onError?: (err: Error) => void;
+  /**
+   * Extra inline styles merged onto the root element. Useful for overriding
+   * CSS custom properties (e.g. `--spoiler-pill-bg`, `--spoiler-bg`).
+   */
+  style?: CSSProperties & { [key: `--${string}`]: string };
+}
+
+export const Spoiler: ForwardRefExoticComponent<SpoilerProps & RefAttributes<HTMLSpanElement>>;
+export default Spoiler;

package/react.jsx

@@ -0,0 +1,168 @@
+/**
+ * spoiler-ui/react
+ * Optional React wrapper — import only if you use React.
+ */
+
+import { useState, useRef, useEffect, forwardRef, useCallback } from 'react';
+import { decodeBase64 } from './spoiler.js';
+
+export const Spoiler = forwardRef(function Spoiler({
+  children,
+  label = 'Spoiler',
+  blurAmount = 6,
+  revealOnClick = true,
+  animationDuration = 300,
+  className = '',
+  src = null,
+  fetchOptions = {},
+  responseType = 'text',
+  encoded = false,
+  icon = undefined,
+  showPill = true,
+  loadingLabel = 'Loading\u2026',
+  errorLabel = 'Failed \u2014 retry?',
+  renderPill = undefined,
+  onReveal = undefined,
+  onError = undefined,
+  style = {},
+}, ref) {
+  // State machine: 'idle' | 'loading' | 'error' | 'revealed'
+  const [state, setState] = useState('idle');
+  const [revealedContent, setRevealedContent] = useState(null);
+  const abortRef = useRef(null);
+
+  // Always-current refs so async callbacks never go stale
+  const onRevealRef = useRef(onReveal);
+  const onErrorRef = useRef(onError);
+  useEffect(() => { onRevealRef.current = onReveal; onErrorRef.current = onError; });
+
+  // Abort in-flight fetch on unmount
+  useEffect(() => () => abortRef.current?.abort(), []);
+
+  const isRevealed = state === 'revealed';
+
+  // icon === false/null → hide; icon === string → custom; undefined → CSS default (👁)
+  const noIcon = icon === false || icon === null;
+  const rootStyle = /** @type {React.CSSProperties} */ ({
+    '--spoiler-blur': `${blurAmount}px`,
+    '--spoiler-duration': `${animationDuration}ms`,
+    ...(typeof icon === 'string' && { '--spoiler-icon': `'${icon}'` }),
+    ...style,
+  });
+
+  const pillLabel = state === 'loading' ? loadingLabel
+                  : state === 'error'   ? errorLabel
+                  : label;
+
+  const handleActivate = useCallback(async () => {
+    if (state !== 'idle' && state !== 'error') return;
+
+    if (src) {
+      abortRef.current?.abort();
+      abortRef.current = new AbortController();
+      setState('loading');
+
+      try {
+        const res = await fetch(src, { signal: abortRef.current.signal, ...fetchOptions });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        const text = await res.text();
+
+        if (abortRef.current.signal.aborted) return;
+
+        setRevealedContent(text);
+        setState('revealed');
+        onRevealRef.current?.(text);
+      } catch (err) {
+        if (err.name === 'AbortError') return;
+        setState('error');
+        console.error('[spoiler-ui] Fetch failed:', err);
+        onErrorRef.current?.(err);
+      }
+    } else if (encoded) {
+      if (typeof children !== 'string') {
+        console.warn('[spoiler-ui] `encoded` prop requires `children` to be a Base64 string.');
+        setState('revealed');
+        onRevealRef.current?.();
+        return;
+      }
+      try {
+        const decoded = decodeBase64(children);
+        setRevealedContent(decoded);
+        setState('revealed');
+        onRevealRef.current?.(decoded);
+      } catch (err) {
+        console.error('[spoiler-ui] Failed to decode Base64 payload:', err);
+        setState('error');
+        onErrorRef.current?.(err);
+      }
+    } else {
+      setState('revealed');
+      onRevealRef.current?.();
+    }
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [state, src, encoded, children, responseType, fetchOptions]);
+
+  const handleKeyDown = useCallback((e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      handleActivate();
+    }
+  }, [handleActivate]);
+
+  const handleOverlayClick = useCallback((e) => {
+    e.stopPropagation();
+    handleActivate();
+  }, [handleActivate]);
+
+  // Determine what to render inside the inner span.
+  // When encoded (pre-reveal) or src-only (no placeholder), render a non-breaking
+  // space so __inner has real line-height. The root also gets data-empty so CSS
+  // switches it to inline-block with min-width — the absolute overlay needs a
+  // proper rectangular containing block, not just an inline line box.
+  const noPlaceholder = !isRevealed && revealedContent === null && (encoded || (!children && src));
+  let innerContent;
+  if (revealedContent !== null) {
+    innerContent = responseType === 'html'
+      ? <span dangerouslySetInnerHTML={{ __html: revealedContent }} />
+      : revealedContent;
+  } else if (noPlaceholder) {
+    innerContent = '\u00A0';
+  } else {
+    innerContent = children;
+  }
+
+  return (
+    <span
+      ref={ref}
+      className={['spoiler-ui', className].filter(Boolean).join(' ')}
+      data-state={state}
+      data-revealed={isRevealed ? 'true' : 'false'}
+      {...(noPlaceholder && { 'data-empty': '' })}
+      {...(noIcon && { 'data-no-icon': '' })}
+      {...(!showPill && { 'data-no-pill': '' })}
+      style={rootStyle}
+      onClick={revealOnClick && !isRevealed ? handleActivate : undefined}
+      onKeyDown={!isRevealed ? handleKeyDown : undefined}
+      tabIndex={isRevealed ? undefined : 0}
+      role={isRevealed ? undefined : 'button'}
+      aria-label={isRevealed ? undefined : `Reveal ${label}`}
+      aria-expanded={isRevealed ? undefined : 'false'}
+    >
+      <span className="spoiler-ui__inner">{innerContent}</span>
+
+      {!isRevealed && (
+        <span
+          className="spoiler-ui__overlay"
+          onClick={!revealOnClick ? handleOverlayClick : undefined}
+          aria-hidden="true"
+        >
+          <span className="spoiler-ui__pill">
+            {renderPill ? renderPill({ state, label: pillLabel }) : pillLabel}
+          </span>
+        </span>
+      )}
+    </span>
+  );
+});
+
+export default Spoiler;

package/spoiler.css

@@ -0,0 +1,217 @@
+/* spoiler-ui — core styles */
+
+.spoiler-ui {
+  --spoiler-blur: 6px;
+  --spoiler-duration: 300ms;
+  --spoiler-bg: rgba(0, 0, 0, 0.05);
+  --spoiler-pill-bg: rgba(0, 0, 0, 0.72);
+  --spoiler-pill-color: #000;
+  --spoiler-pill-font: inherit;
+  --spoiler-radius: 4px;
+  --spoiler-error-bg: #c0392b;
+  --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;
+  --spoiler-pill-radius: 100px;
+  --spoiler-shimmer-color: rgba(255, 255, 255, 0.5);
+  --spoiler-shimmer-duration: 2.4s;
+
+  position: relative;
+  display: inline;
+  margin-inline: var(--spoiler-margin-inline, 3px);
+  cursor: pointer;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+/* ── Content layer ── */
+.spoiler-ui__inner {
+  display: inline;
+  transition: filter var(--spoiler-duration) ease,
+              opacity var(--spoiler-duration) ease;
+  will-change: filter, opacity;
+  filter: blur(var(--spoiler-blur));
+  opacity: 0.35;
+  pointer-events: none;
+}
+
+/*
+ * No-placeholder mode (encoded or src-only).
+ * Switch root to inline-block so it forms a proper rectangular containing block
+ * for the absolutely-positioned overlay. The   inside __inner provides height;
+ * min-width ensures the pill label fits.
+ */
+.spoiler-ui[data-empty] {
+  display: inline-block;
+  min-width: 5em;
+  vertical-align: baseline;
+}
+
+/* ── Overlay ── */
+.spoiler-ui__overlay {
+  position: absolute;
+  inset: -2px -4px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: var(--spoiler-radius);
+  background:
+    linear-gradient(
+      105deg,
+      transparent 30%,
+      var(--spoiler-shimmer-color) 50%,
+      transparent 70%
+    )
+    -200% 0 / 200% 100% no-repeat,
+    var(--spoiler-bg);
+  animation: spoiler-shimmer var(--spoiler-shimmer-duration) ease-in-out infinite;
+  transition: opacity var(--spoiler-duration) ease;
+  outline: none;
+}
+
+@keyframes spoiler-shimmer {
+  0%   { background-position: -200% 0, 0 0; }
+  60%  { background-position:  200% 0, 0 0; }
+  100% { background-position:  200% 0, 0 0; }
+}
+
+.spoiler-ui__overlay:focus-visible {
+  box-shadow: 0 0 0 2px currentColor;
+}
+
+/* ── Pill label ── */
+.spoiler-ui__pill {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spoiler-pill-gap);
+  padding: var(--spoiler-pill-padding);
+  border-radius: var(--spoiler-pill-radius);
+  background: var(--spoiler-pill-bg);
+  color: var(--spoiler-pill-color);
+  font-family: var(--spoiler-pill-font);
+  font-size: var(--spoiler-pill-font-size);
+  font-weight: var(--spoiler-pill-font-weight);
+  letter-spacing: var(--spoiler-pill-letter-spacing);
+  white-space: nowrap;
+  pointer-events: none;
+  transition: transform 150ms ease, opacity 150ms ease, background 150ms ease;
+}
+
+/* Eye icon — default idle state */
+.spoiler-ui__pill::before {
+  content: var(--spoiler-icon, '👁');
+  font-size: 0.9em;
+}
+
+/* Hidden icon — set via icon={false} prop or data-no-icon attribute */
+.spoiler-ui[data-no-icon] .spoiler-ui__pill::before {
+  display: none;
+}
+
+.spoiler-ui:hover .spoiler-ui__pill {
+  transform: scale(1.06);
+}
+
+/* ── No-pill mode ── */
+.spoiler-ui[data-no-pill] .spoiler-ui__pill {
+  display: none;
+}
+
+/* ── Loading state ── */
+.spoiler-ui[data-state='loading'] {
+  cursor: wait;
+  pointer-events: none; /* CSS-level guard against double-click */
+}
+
+.spoiler-ui[data-state='loading'] .spoiler-ui__pill {
+  opacity: 0.85;
+}
+
+.spoiler-ui[data-state='loading'] .spoiler-ui__pill::before {
+  content: '';
+  display: inline-block;
+  width: 0.7em;
+  height: 0.7em;
+  border: 1.5px solid currentColor;
+  border-top-color: transparent;
+  border-radius: 50%;
+  animation: spoiler-spin 0.6s linear infinite;
+  flex-shrink: 0;
+}
+
+@keyframes spoiler-spin {
+  to { transform: rotate(360deg); }
+}
+
+/* ── Error state ── */
+.spoiler-ui[data-state='error'] .spoiler-ui__pill {
+  background: var(--spoiler-error-bg);
+}
+
+.spoiler-ui[data-state='error'] .spoiler-ui__pill::before {
+  content: '⚠';
+  font-size: 0.9em;
+}
+
+/* ── Revealed state ── */
+.spoiler-ui[data-state='revealed'],
+.spoiler-ui[data-revealed='true'] {
+  cursor: auto;
+  -webkit-user-select: auto;
+  user-select: auto;
+}
+
+.spoiler-ui[data-state='revealed'] .spoiler-ui__inner,
+.spoiler-ui[data-revealed='true'] .spoiler-ui__inner {
+  filter: blur(0);
+  opacity: 1;
+  will-change: auto;
+  pointer-events: auto;
+}
+
+.spoiler-ui[data-state='revealed'] .spoiler-ui__overlay,
+.spoiler-ui[data-revealed='true'] .spoiler-ui__overlay {
+  opacity: 0;
+  pointer-events: none;
+}
+
+/*
+ * ── Dark-mode ──
+ * No automatic dark-mode overrides are applied by the library.
+ * Override the CSS variables in your own stylesheet to handle dark mode:
+ *
+ *   @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;
+ *     }
+ *   }
+ */
+
+/* ── Reduced motion ── */
+@media (prefers-reduced-motion: reduce) {
+  .spoiler-ui__inner,
+  .spoiler-ui__overlay,
+  .spoiler-ui__pill {
+    transition: none;
+    animation: none;
+  }
+
+  /* Replace spin with pulse for loading indicator */
+  .spoiler-ui[data-state='loading'] .spoiler-ui__pill::before {
+    animation: spoiler-pulse 1s ease infinite;
+    border: none;
+    content: '…';
+    width: auto;
+    height: auto;
+  }
+}
+
+@keyframes spoiler-pulse {
+  0%, 100% { opacity: 1; }
+  50%       { opacity: 0.3; }
+}

package/spoiler.d.ts

@@ -0,0 +1,100 @@
+export interface SpoilerOptions {
+  /** Label shown on the reveal pill. Default: `'Spoiler'` */
+  label?: string;
+  /** Blur amount in px while hidden. Default: `6` */
+  blurAmount?: number;
+  /** Click anywhere on the element to reveal. Default: `true` */
+  revealOnClick?: boolean;
+  /** CSS transition duration in ms. Default: `300` */
+  animationDuration?: number;
+  /** Extra CSS class added to the root element. Default: `''` */
+  className?: string;
+  /**
+   * URL to fetch content from on reveal. When set, the `content` parameter
+   * is optional (used as a blurred placeholder until the fetch completes).
+   */
+  src?: string;
+  /** Options passed directly to `fetch()`. Default: `{}` */
+  fetchOptions?: RequestInit;
+  /**
+   * How to inject fetched or decoded content into the DOM.
+   * - `'text'` (default): sets `textContent` — safe against XSS
+   * - `'html'`: sets `innerHTML` — XSS opt-in, caller's responsibility
+   */
+  responseType?: 'text' | 'html';
+  /**
+   * When `true`, the `content` string is treated as Base64-encoded text.
+   * It is stored in a data attribute and decoded only when the user reveals —
+   * plaintext never appears in the DOM beforehand.
+   *
+   * Note: Base64 is obscurity, not encryption. A determined user can still
+   * decode it from page source. Use `src` for true server-gated hiding.
+   */
+  encoded?: boolean;
+  /**
+   * Override the pill icon shown before the label.
+   * - `string` — replaces the default 👁 with the given character/emoji
+   * - `false` or `null` — hides the icon entirely
+   * - `undefined` (default) — uses the CSS `--spoiler-icon` variable (👁)
+   */
+  icon?: string | false | null;
+  /** Hide the pill label button. The overlay and shimmer still show; click still reveals. Default: `true` */
+  showPill?: boolean;
+  /** Text shown on the pill while a fetch is in progress. Default: `'Loading…'` */
+  loadingLabel?: string;
+  /** Text shown on the pill when a fetch or decode fails. Default: `'Failed — retry?'` */
+  errorLabel?: string;
+  /**
+   * Callback fired after a successful reveal.
+   * - Fetch mode: receives the fetched content string.
+   * - Encoded mode: receives the decoded content string.
+   * - Plain mode: receives the element's text content.
+   */
+  onReveal?: (content: string) => void;
+  /** Callback fired when a fetch or decode fails. Receives the Error object. */
+  onError?: (err: Error) => void;
+}
+
+/**
+ * Creates a spoiler element wrapping the given content.
+ * Pass `null` or omit `content` when using the `src` option.
+ */
+export function createSpoiler(
+  content: string | Element | null | undefined,
+  options?: SpoilerOptions
+): HTMLElement;
+
+/**
+ * Scans the DOM for `[data-spoiler]` elements and converts them
+ * into interactive spoiler components.
+ *
+ * Supported data attributes:
+ * - `data-spoiler`                  — label text (required to activate)
+ * - `data-spoiler-blur`             — blur amount in px
+ * - `data-spoiler-duration`         — animation duration in ms
+ * - `data-spoiler-src`              — URL to fetch content from on reveal
+ * - `data-spoiler-response-type`    — `'text'` (default) or `'html'`
+ * - `data-spoiler-encoded`          — Base64-encoded content string (decoded on reveal)
+ * - `data-spoiler-reveal-on-click`  — set to `'false'` to restrict reveal to the pill button only
+ * - `data-spoiler-show-pill`        — set to `'false'` to hide the pill label button
+ * - `data-spoiler-loading-label`    — pill text while fetching (default: `'Loading…'`)
+ * - `data-spoiler-error-label`      — pill text on failure (default: `'Failed — retry?'`)
+ * - `data-spoiler-class`            — extra CSS class added to the root element
+ * - `data-spoiler-icon`             — pill icon: `'false'` hides it, any other string replaces the default 👁
+ *
+ * @param scope - Root element to search within. Defaults to `document`.
+ */
+export function initSpoilers(scope?: Document | HTMLElement): void;
+
+/**
+ * Encodes a string to Base64 with full Unicode support.
+ * Use this to prepare content before embedding it in your HTML or JS.
+ */
+export function encodeBase64(str: string): string;
+
+/**
+ * Decodes a Base64 string with full Unicode support.
+ */
+export function decodeBase64(b64: string): string;
+
+export default createSpoiler;