@nawa-captcha/svelte 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @nawa-captcha/svelte
 
-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.
+**Nawa Captcha** — a self-hosted, privacy-friendly and accessible puzzle CAPTCHA. A drop-in alternative to reCAPTCHA, hCaptcha and Turnstile with no third-party tracking: your server issues the challenge and verifies the answer.
+
+This package: Svelte 5 component.
+
+- 🧩 38 challenge types you choose from (one, two or many, per action): slider jigsaws, rotate, drag to the shadow, jigsaw, hold, icon/colour/clock/symmetry grids, match pairs, tap in order, spell, order and story tiles, connect the dots, maze, math, dice, invisible proof-of-work, an accessible text question and an audio challenge — [see them live](https://oriebalzyuot96.github.io/nawa-captcha/#playground)
+- 🔒 Answers are sealed (AES-256-GCM) and never reach the browser; pass tokens are signed and single-use
+- ♿ Keyboard, touch and screen-reader friendly (text question and audio challenge); Arabic and English; RTL
+- 🎨 Premium 3D design, six themes in light and dark plus high contrast (WCAG 2.2 AA), Pelagic UI tokens, optional sound effects
+- 🖥️ Backends: Node.js / Express and ASP.NET Core (`NawaCaptcha.AspNetCore`, coming to NuGet)
+
+## Install
+
+> **Coming to npm.** `@nawa-captcha/svelte` is published once the `@nawa-captcha` npm organisation exists. Until then, build it from the [repository](https://github.com/oriebalzyuot96/nawa-captcha) (`npm install && npm run build`, then `npm pack -w @nawa-captcha/svelte`).
+
+```bash
+npm i @nawa-captcha/svelte
+# or
+yarn add @nawa-captcha/svelte
+# or
+pnpm add @nawa-captcha/svelte
+```
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { NawaCaptcha } from '@nawa-captcha/svelte';
+  let token = $state('');
+</script>
+
+<NawaCaptcha bind:token siteKey="main" action="login" lang="en" />
+<button disabled={!token}>Sign in</button>
+```
+
+`types` narrows the server's allowed puzzles: `<NawaCaptcha bind:token action="login" types={['slider', 'pairs']} />` (never widens them).
+
+Then verify on your backend before trusting the request — see the [full guide](https://github.com/oriebalzyuot96/nawa-captcha#readme).
+
+📖 Docs: https://oriebalzyuot96.github.io/nawa-captcha/ · 💻 Source: https://github.com/oriebalzyuot96/nawa-captcha
+
+MIT © oriebalzyuot96

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "@nawa-captcha/svelte",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Nawa Captcha for Svelte 5: accessible, self-hosted puzzle CAPTCHA component — a privacy-friendly reCAPTCHA alternative.",
+  "license": "MIT",
+  "type": "module",
+  "svelte": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "svelte": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "typecheck": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings"
+  },
+  "dependencies": {
+    "@nawa-captcha/widget": "0.1.1"
+  },
+  "peerDependencies": {
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "svelte": "^5.40.0",
+    "svelte-check": "^4.3.0"
+  },
+  "keywords": [
+    "svelte",
+    "svelte5",
+    "svelte-component",
+    "captcha",
+    "recaptcha-alternative",
+    "hcaptcha-alternative",
+    "turnstile-alternative",
+    "self-hosted-captcha",
+    "accessible-captcha",
+    "puzzle-captcha",
+    "slider-captcha",
+    "privacy",
+    "gdpr",
+    "bot-protection",
+    "anti-spam",
+    "proof-of-work",
+    "nawa-captcha",
+    "pelagic-ui",
+    "arabic",
+    "rtl"
+  ],
+  "homepage": "https://oriebalzyuot96.github.io/nawa-captcha/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oriebalzyuot96/nawa-captcha.git",
+    "directory": "packages/svelte"
+  },
+  "bugs": "https://github.com/oriebalzyuot96/nawa-captcha/issues",
+  "author": "oriebalzyuot96",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/NawaCaptcha.svelte

@@ -0,0 +1,69 @@
+<!--
+  Svelte 5 wrapper for <nawa-captcha>.
+  <NawaCaptcha bind:token action="login" lang="ar" onverified={(d) => …} />
+  `token` is bindable: it holds the pass token ('' until verified). Call `reset()` (via bind:this)
+  after the token has been used, because pass tokens are single-use.
+-->
+<script lang="ts">
+  import '@nawa-captcha/widget';
+  import type { NawaCaptchaElement, NawaCaptchaErrorDetail, NawaCaptchaVerifiedDetail } from '@nawa-captcha/widget';
+
+  interface Props {
+    siteKey?: string;
+    endpoint?: string;
+    action?: string;
+    lang?: 'ar' | 'en';
+    name?: string;
+    type?: string;
+    /** Narrows the server's allowed puzzle types (array or comma-separated). Never widens it. */
+    types?: string | readonly string[];
+    theme?: string;
+    appearance?: 'auto' | 'light' | 'dark' | 'high-contrast';
+    sound?: boolean;
+    volume?: number;
+    muted?: boolean;
+    token?: string;
+    onverified?: (detail: NawaCaptchaVerifiedDetail) => void;
+    onexpired?: () => void;
+    onerror?: (detail: NawaCaptchaErrorDetail) => void;
+  }
+
+  let { siteKey, endpoint, action, lang, name, type, types, theme, appearance, sound, volume, muted, token = $bindable(''), onverified, onexpired, onerror }: Props = $props();
+
+  let el: NawaCaptchaElement | undefined = $state();
+  const typesAttr = $derived(types === undefined ? undefined : typeof types === 'string' ? types : types.join(','));
+
+  $effect(() => {
+    const node = el;
+    if (!node) return;
+    const verified = (e: Event): void => {
+      const detail = (e as CustomEvent<NawaCaptchaVerifiedDetail>).detail;
+      token = detail.token;
+      onverified?.(detail);
+    };
+    const expired = (): void => {
+      token = '';
+      onexpired?.();
+    };
+    const failed = (e: Event): void => {
+      token = '';
+      onerror?.((e as CustomEvent<NawaCaptchaErrorDetail>).detail);
+    };
+    node.addEventListener('nawa-captcha:verified', verified);
+    node.addEventListener('nawa-captcha:expired', expired);
+    node.addEventListener('nawa-captcha:error', failed);
+    return () => {
+      node.removeEventListener('nawa-captcha:verified', verified);
+      node.removeEventListener('nawa-captcha:expired', expired);
+      node.removeEventListener('nawa-captcha:error', failed);
+    };
+  });
+
+  /** Clears the token and loads a fresh challenge. */
+  export function reset(): void {
+    token = '';
+    el?.reset();
+  }
+</script>
+
+<nawa-captcha bind:this={el} site-key={siteKey} {endpoint} {action} {lang} {name} {type} types={typesAttr} {theme} {appearance} {sound} {volume} {muted}></nawa-captcha>

package/src/elements.d.ts

@@ -0,0 +1,22 @@
+import type { HTMLAttributes } from 'svelte/elements';
+
+// Lets Svelte's type checker know the <nawa-captcha> custom element and its attributes.
+declare module 'svelte/elements' {
+  interface SvelteHTMLElements {
+    'nawa-captcha': HTMLAttributes<HTMLElement> & {
+      'site-key'?: string | undefined;
+      endpoint?: string | undefined;
+      action?: string | undefined;
+      name?: string | undefined;
+      type?: string | undefined;
+      types?: string | undefined;
+      theme?: string | undefined;
+      appearance?: string | undefined;
+      sound?: boolean | string | undefined;
+      volume?: number | string | undefined;
+      muted?: boolean | string | undefined;
+    };
+  }
+}
+
+export {};

package/src/index.d.ts

@@ -0,0 +1,31 @@
+import type { Component } from 'svelte';
+import type { NawaCaptchaErrorDetail, NawaCaptchaVerifiedDetail } from '@nawa-captcha/widget';
+
+export type { NawaCaptchaErrorDetail, NawaCaptchaVerifiedDetail };
+
+export interface NawaCaptchaProps {
+  siteKey?: string;
+  endpoint?: string;
+  action?: string;
+  lang?: 'ar' | 'en';
+  name?: string;
+  type?: string;
+  /** Narrows the server's allowed puzzle types. Never widens it. */
+  types?: string | readonly string[];
+  /** Theme preset or appearance shorthand (see the widget README). */
+  theme?: string;
+  appearance?: 'auto' | 'light' | 'dark' | 'high-contrast';
+  sound?: boolean;
+  volume?: number;
+  muted?: boolean;
+  token?: string;
+  onverified?: (detail: NawaCaptchaVerifiedDetail) => void;
+  onexpired?: () => void;
+  onerror?: (detail: NawaCaptchaErrorDetail) => void;
+}
+
+export declare const NawaCaptcha: Component<NawaCaptchaProps, { reset(): void }, 'token'>;
+/** @deprecated Renamed to {@link NawaCaptcha} (Nawa Guard is now Nawa Captcha). */
+export declare const NawaGuard: typeof NawaCaptcha;
+/** @deprecated Renamed to NawaCaptchaProps. */
+export type NawaGuardProps = NawaCaptchaProps;

package/src/index.js

@@ -0,0 +1,3 @@
+export { default as NawaCaptcha } from './NawaCaptcha.svelte';
+/** @deprecated Renamed to NawaCaptcha (Nawa Guard is now Nawa Captcha). */
+export { default as NawaGuard } from './NawaCaptcha.svelte';