readwhitepaper-embed 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dobestan
+
+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,206 @@
+# readwhitepaper-embed
+
+[![npm](https://img.shields.io/npm/v/readwhitepaper-embed)](https://www.npmjs.com/package/readwhitepaper-embed)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://www.npmjs.com/package/readwhitepaper-embed)
+
+Embed **ReadWhitepaper** widgets on any website. Display blockchain whitepaper cards, glossary terms, guides, and search on your blog, documentation, or wiki. **4 widget types**, zero dependencies, Shadow DOM style isolation, 4 built-in themes (light, dark, sepia, auto), 2 styles (modern, minimal), and live data from [readwhitepaper.com](https://readwhitepaper.com).
+
+ReadWhitepaper is a blockchain whitepaper database featuring 30 whitepapers (Bitcoin, Ethereum, Solana, Cardano, Polkadot, and more), 163 glossary terms covering blockchain fundamentals, DeFi protocols, consensus mechanisms, and cryptographic primitives, all available in 15 languages.
+
+Every widget includes a "Powered by ReadWhitepaper" backlink directing readers to the full reference.
+
+> **Try the interactive widget builder at [widget.readwhitepaper.com](https://widget.readwhitepaper.com)**
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Widget Types](#widget-types)
+- [Widget Options](#widget-options)
+- [Themes](#themes)
+- [Styles](#styles)
+- [Web Components](#web-components-custom-elements)
+- [Examples](#examples)
+- [CDN Options](#cdn-options)
+- [What You Can Embed](#what-you-can-embed)
+- [Technical Details](#technical-details)
+- [Learn More About Blockchain Whitepapers](#learn-more-about-blockchain-whitepapers)
+- [License](#license)
+
+## Quick Start
+
+```html
+<!-- Place widget div where you want it to appear -->
+<div data-readwhitepaper="entity" data-slug="bitcoin" data-theme="light"></div>
+
+<!-- Load the embed script once, anywhere on the page -->
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1/dist/embed.min.js"></script>
+```
+
+That's it. The widget fetches data from the ReadWhitepaper API and renders with full style isolation.
+
+## Widget Types
+
+| Type | Usage | Description |
+|------|-------|-------------|
+| `entity` | `<div data-readwhitepaper="entity" data-slug="..."></div>` | Whitepaper card — title, authors, year, category, abstract excerpt |
+| `glossary` | `<div data-readwhitepaper="glossary" data-slug="..."></div>` | Blockchain glossary term with cross-references |
+| `guide` | `<div data-readwhitepaper="guide" data-slug="..."></div>` | Guide summary card with description |
+| `search` | `<div data-readwhitepaper="search" data-slug="..."></div>` | Search box linking to the full whitepaper database |
+
+## Widget Options
+
+| Attribute | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `data-readwhitepaper` | entity, glossary, guide, search | required | Widget type |
+| `data-slug` | e.g. "bitcoin", "proof-of-work" | -- | Entity or term slug from ReadWhitepaper |
+| `data-theme` | light, dark, sepia, auto | light | Visual theme (`auto` follows OS preference) |
+| `data-styleVariant` | modern, minimal | modern | Widget design style |
+| `data-size` | default, compact, large | default | Widget max-width (280/420/720px) |
+| `data-placeholder` | any string | "Search Whitepapers..." | Search box placeholder text |
+| `data-no-snippet` | true | -- | Disable DefinedTerm JSON-LD injection |
+
+## Themes
+
+```html
+<!-- Light (default) — clean white background -->
+<div data-readwhitepaper="entity" data-slug="bitcoin" data-theme="light"></div>
+
+<!-- Dark — dark background for dark-mode sites -->
+<div data-readwhitepaper="entity" data-slug="bitcoin" data-theme="dark"></div>
+
+<!-- Sepia — warm paper-like tones -->
+<div data-readwhitepaper="entity" data-slug="bitcoin" data-theme="sepia"></div>
+
+<!-- Auto — follows OS dark/light preference via matchMedia -->
+<div data-readwhitepaper="entity" data-slug="bitcoin" data-theme="auto"></div>
+```
+
+## Styles
+
+```html
+<!-- Modern (default) — gradient accent header, rounded corners, spacious -->
+<div data-readwhitepaper="entity" data-slug="ethereum" data-styleVariant="modern"></div>
+
+<!-- Minimal — monospace font, thin border, flat design for dev docs -->
+<div data-readwhitepaper="entity" data-slug="ethereum" data-styleVariant="minimal"></div>
+```
+
+## Web Components (Custom Elements)
+
+As an alternative to `data-*` attributes, use native HTML custom elements:
+
+```html
+<readwhitepaper-entity slug="bitcoin" theme="dark"></readwhitepaper-entity>
+<readwhitepaper-glossary slug="proof-of-work"></readwhitepaper-glossary>
+<readwhitepaper-search placeholder="Search whitepapers..."></readwhitepaper-search>
+
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1/dist/embed.min.js"></script>
+```
+
+Use `style-variant` (not `style`) to avoid conflicts with the HTML reserved `style` attribute.
+
+## Examples
+
+### Whitepaper Card
+
+```html
+<!-- Bitcoin whitepaper card with dark theme -->
+<div data-readwhitepaper="entity" data-slug="bitcoin" data-theme="dark"></div>
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1/dist/embed.min.js"></script>
+```
+
+### Blockchain Glossary Term
+
+```html
+<!-- Proof of Work definition with DefinedTerm JSON-LD injection -->
+<div data-readwhitepaper="glossary" data-slug="proof-of-work" data-theme="light"></div>
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1/dist/embed.min.js"></script>
+```
+
+### Search Box
+
+```html
+<div data-readwhitepaper="search" data-placeholder="Search blockchain whitepapers..."></div>
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1/dist/embed.min.js"></script>
+```
+
+## CDN Options
+
+### jsDelivr (recommended)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1/dist/embed.min.js"></script>
+```
+
+### Specific version (production stability)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/readwhitepaper-embed@1.0.0/dist/embed.min.js"></script>
+```
+
+### npm (for bundlers)
+
+```bash
+npm install readwhitepaper-embed
+```
+
+```javascript
+import 'readwhitepaper-embed';
+```
+
+## What You Can Embed
+
+### Blockchain Whitepapers
+
+ReadWhitepaper hosts the foundational documents that define the blockchain ecosystem. Each whitepaper card displays the document title, authors, publication year, category, and an abstract excerpt:
+
+- **Bitcoin** (2008) -- Satoshi Nakamoto's original peer-to-peer electronic cash system paper
+- **Ethereum** (2013) -- Vitalik Buterin's proposal for a programmable blockchain with smart contracts
+- **Solana** (2017) -- Proof of History consensus for high-throughput transactions
+- **Cardano** (2017) -- Peer-reviewed, evidence-based blockchain platform
+- **Polkadot** (2016) -- Heterogeneous multi-chain framework for cross-chain interoperability
+- **Chainlink** (2017) -- Decentralized oracle network bridging on-chain and off-chain data
+
+### Blockchain Glossary
+
+163 terms covering the full spectrum of blockchain technology:
+
+- **Consensus mechanisms**: Proof of Work, Proof of Stake, Delegated PoS, BFT
+- **DeFi protocols**: AMM, liquidity pools, yield farming, flash loans, impermanent loss
+- **Cryptographic primitives**: hash functions, Merkle trees, digital signatures, zero-knowledge proofs
+- **Network architecture**: nodes, validators, sharding, layer 2, sidechains, rollups
+- **Token standards**: ERC-20, ERC-721, ERC-1155, BEP-20
+
+### Guides
+
+In-depth guides explaining blockchain concepts, protocol comparisons, and technical deep dives.
+
+## Technical Details
+
+- **Shadow DOM**: Complete style isolation -- no CSS conflicts with your site
+- **Zero dependencies**: No jQuery, React, or any external library
+- **2 styles**: Modern (accent gradients) and Minimal (monospace, flat design)
+- **4 themes**: Light, Dark, Sepia, Auto (OS preference detection with matchMedia listener)
+- **CORS**: ReadWhitepaper API has CORS enabled for all origins
+- **MutationObserver**: Works with dynamically added elements (SPAs, React, Vue)
+- **IntersectionObserver**: Lazy loading -- widgets only fetch when entering viewport (200px margin)
+- **Rich Snippets**: DefinedTerm JSON-LD injected for glossary widgets (opt-out via data-no-snippet)
+- **sessionStorage cache**: 5-minute TTL reduces API calls on page navigation
+
+## Learn More About Blockchain Whitepapers
+
+Visit [readwhitepaper.com](https://readwhitepaper.com) -- ReadWhitepaper is a comprehensive blockchain whitepaper database with full-text access, glossary, and multi-language translations.
+
+- **All whitepapers**: [readwhitepaper.com](https://readwhitepaper.com)
+- **Glossary**: [readwhitepaper.com/glossary/](https://readwhitepaper.com/glossary/)
+- **API docs**: [readwhitepaper.com/developers/](https://readwhitepaper.com/developers/)
+- **Widget builder**: [widget.readwhitepaper.com](https://widget.readwhitepaper.com)
+- **npm package**: [npmjs.com/package/readwhitepaper-embed](https://www.npmjs.com/package/readwhitepaper-embed)
+- **GitHub**: [github.com/dobestan/readwhitepaper-embed](https://github.com/dobestan/readwhitepaper-embed)
+
+## License
+
+MIT -- see [LICENSE](./LICENSE).
+
+Built by [dobestan](https://github.com/dobestan).