readme

LICENSE

@@ -0,0 +1,9 @@
+BSD with attribution
+BSD-3-Clause-Attribution
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+4. Redistributions of any form whatsoever must retain the following acknowledgment: 'This product includes software developed by "Kieran Simkin" (https://nft-playground.dev/).'
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,225 @@
+## `<SmartNFTPortal>`
+
+A `<SmartNFTPortal>` is a React control which renders Smart NFTs in the browser. This widget takes care of the `&lt;iframe&gt;` sandbox, and provides the Smart NFT Javascript API to any NFT which is rendered inside it. This provides a great deal of extra power to Javascript NFTs, enabling them to respond to changes on the blockchain, as well as load additional assets such as Javascript libraries, images, and other data directly from the blockchain. 
+
+While this API provides a lot of additional functionality to NFTs inside the sandbox, it's important to note that they are still fully sandboxed - this control handles all the necessary inter-process communication between the sandboxed iframe and its parent document using the sendMessage() API. 
+
+[Click here to see it in action in the Smart NFT Playground](https://nft-playground.dev/).
+
+[The source code of the Smart NFT Playground is also available](https://github.com/kieransimkin/cip54-playground).
+
+[libcip54 provides the backend queries necessary to support this API on Cardano](https://github.com/kieransimkin/libcip54).
+
+
+### Installing
+
+```bash
+$ npm install smartnftportal
+or
+$ yarn add smartnftportal
+```
+
+### Exports
+
+The default export is `<SmartNFTPortal>`.
+To use it:
+
+```js
+import { SmartNFTPortal } from "smartnftportal"
+```
+
+### React Smart NFT Portal Usage
+
+At minimum you must pass in the NFT metadata, and the smartImports structure, which has been generated by [libcip54](https://github.com/kieransimkin/libcip54).
+Libcip54 is a node.js library which provides the backend queries to import this data from the Cardano blockchain via the DBSync chain indexer - so if you have your own DBSync server, this is the preferred option. If you don't have a DBSync server, then you can query the [Plutus.art](https://plutus.art/) API for the same data.
+
+```js
+import React from 'react'
+import { SmartNFTPortal } from 'smartnftportal'
+import axios from "axios"
+
+function App() {
+  const [nft,setNft] = React.useState(null);
+  React.useEffect(()=> { 
+    axios.get('https://plutus-art-dev.herokuapp.com/asset/1eaf3b3ffb75ff27c43c512c23c6450b307f138281efb1d690b8465231').then((d)=>{
+        setNft(d.data);
+    });
+  },[]);
+  return (
+    <div className="App">
+      <header className="App-header">
+        <div style={{ width: 400 }}>
+          <SmartNFTPortal 
+            smartImports={nft?.smartImports}
+            metadata={nft?.metadata}
+            loading={!nft}
+             />
+        </div>
+      </header>
+    </div>
+  )
+}
+
+export default App
+```
+
+### &lt;SmartNFTPortal /&gt;
+
+The following properties are available on the control:
+
+#### loading: `boolean`
+
+When true, the control will assume the metadata and smartImports fields haven't been populated yet and will display a loading message
+
+#### smartImports: `object`
+
+This is a complex object containing all the imports from the blockchain - intended to be generated by libcip54
+
+#### metadata: `object`
+
+This is a copy of the NFT's metadata - if it's a CIP68 asset, the metadata should be converted from the CBOR into a JSON format that matches CIP25 assets. 
+
+#### loadingContent: `object`
+
+> default: `<div>Loading...</div>`
+
+A react control or JSX tag to display when the control is loading
+
+#### apiRoot: `string`
+
+> default: null
+
+The initial smartImport object should contain all the data needed to initially render the NFT, but some NFTs may choose to request additional data as they run - the necessary endpoints are provided in libcip54.
+
+#### className: `string`
+
+> default: ``
+
+Provide a custom class name for the iframe tag itself.
+
+#### focus: `boolean`
+
+> default: false
+
+If true, the iframe will attempt to request focus() after the initial document has loaded. 
+
+#### onFocus: `function`
+
+> default null
+
+A callback function for the focus event
+
+#### onBlur: `function`
+
+> default null
+
+A callback function for the blur event
+
+#### style: `object`
+
+> default: null
+
+CSS Styles
+
+#### random: `number`
+
+> default: null
+
+Just a quick way to trigger a refresh of the component
+
+#### inactiveHtmlStyle: `string`
+
+> default: ''
+
+A snippet of CSS to add to the `<body>` tag within the sandbox when is not focused
+
+#### activeHtmlStyle: `string`
+
+> default: ''
+
+A snippet of CSS to add to the `<body>` tag within the sandbox when is focused
+
+#### onReady: `function`
+
+> default null
+
+A callback function for when the iframe's dom is ready
+
+#### onScroll: `function`
+
+> default null
+
+A callback function to get the scroll event from within the iframe
+
+#### onMouseOver: `function`
+
+> default null
+
+A callback function for the mouseover event
+
+#### onMouseOut: `function`
+
+> default null
+
+A callback function for the mouseout event
+
+#### onClick: `function`
+
+> default null
+
+A callback function for the click event
+
+#### onMouseDown: `function`
+
+> default null
+
+A callback function for the mousedown event
+
+#### onMouseUp: `function`
+
+> default null
+
+A callback function for the mouseup event
+
+#### onMouseMove: `function`
+
+> default null
+
+A callback function for the mousemove event
+
+#### onContextMenu: `function`
+
+> default null
+
+A callback function for the contextmenu event
+
+#### onDblClick: `function`
+
+> default null
+
+A callback function for the dblClick event
+
+#### onTouchStart: `function`
+
+> default null
+
+A callback function for the touchstart event
+
+#### onTouchEnd: `function`
+
+> default null
+
+A callback function for the touchend event
+
+#### onTouchMove: `function`
+
+> default null
+
+A callback function for the touchmove event
+
+#### onTouchCancel: `function`
+
+> default null
+
+A callback function for the touchcancel event
+