michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this
michael@0:  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: "use strict";
michael@0: 
michael@0: module.metadata = {
michael@0:   "stability": "unstable"
michael@0: };
michael@0: 
michael@0: const { EventEmitter } = require('../deprecated/events');
michael@0: const { validateOptions } = require('../deprecated/api-utils');
michael@0: const { isValidURI, URL } = require('../url');
michael@0: const file = require('../io/file');
michael@0: const { contract } = require('../util/contract');
michael@0: const { isString, instanceOf } = require('../lang/type');
michael@0: 
michael@0: const LOCAL_URI_SCHEMES = ['resource', 'data'];
michael@0: 
michael@0: // Returns `null` if `value` is `null` or `undefined`, otherwise `value`.
michael@0: function ensureNull(value) value == null ? null : value
michael@0: 
michael@0: // map of property validations
michael@0: const valid = {
michael@0:   contentURL: {
michael@0:     map: function(url) !url ? ensureNull(url) : url.toString(), 
michael@0:     is: ['undefined', 'null', 'string'],
michael@0:     ok: function (url) {
michael@0:       if (url === null)
michael@0:         return true;
michael@0:       return isValidURI(url);
michael@0:     },
michael@0:     msg: 'The `contentURL` option must be a valid URL.'
michael@0:   },
michael@0:   contentScriptFile: {
michael@0:     is: ['undefined', 'null', 'string', 'array', 'object'],
michael@0:     map: ensureNull,
michael@0:     ok: function(value) {
michael@0:       if (value === null)
michael@0:         return true;
michael@0: 
michael@0:       value = [].concat(value);
michael@0: 
michael@0:       // Make sure every item is a string or an
michael@0:       // URL instance, and also a local file URL.
michael@0:       return value.every(function (item) {
michael@0: 
michael@0:         if (!isString(item) && !(item instanceof URL)) 
michael@0:           return false;
michael@0: 
michael@0:         try {
michael@0:           return ~LOCAL_URI_SCHEMES.indexOf(URL(item).scheme);
michael@0:         }
michael@0:         catch(e) {
michael@0:           return false;
michael@0:         }
michael@0:       });
michael@0: 
michael@0:     },
michael@0:     msg: 'The `contentScriptFile` option must be a local URL or an array of URLs.'
michael@0:   },
michael@0:   contentScript: {
michael@0:     is: ['undefined', 'null', 'string', 'array'],
michael@0:     map: ensureNull,
michael@0:     ok: function(value) {
michael@0:       return !Array.isArray(value) || value.every(
michael@0:         function(item) { return typeof item === 'string' }
michael@0:       );
michael@0:     },
michael@0:     msg: 'The `contentScript` option must be a string or an array of strings.'
michael@0:   },
michael@0:   contentScriptWhen: {
michael@0:     is: ['string'],
michael@0:     ok: function(value) { return ~['start', 'ready', 'end'].indexOf(value) },
michael@0:     map: function(value) {
michael@0:       return value || 'end';
michael@0:     },
michael@0:     msg: 'The `contentScriptWhen` option must be either "start", "ready" or "end".'
michael@0:   },
michael@0:   contentScriptOptions: {
michael@0:     ok: function(value) {
michael@0:       if ( value === undefined ) { return true; }
michael@0:       try { JSON.parse( JSON.stringify( value ) ); } catch(e) { return false; }
michael@0:       return true;
michael@0:     },
michael@0:     map: function(value) 'undefined' === getTypeOf(value) ? null : value,
michael@0:     msg: 'The contentScriptOptions should be a jsonable value.'
michael@0:   }
michael@0: };
michael@0: exports.validationAttributes = valid;
michael@0: 
michael@0: /**
michael@0:  * Shortcut function to validate property with validation.
michael@0:  * @param {Object|Number|String} suspect
michael@0:  *    value to validate
michael@0:  * @param {Object} validation
michael@0:  *    validation rule passed to `api-utils`
michael@0:  */
michael@0: function validate(suspect, validation) validateOptions(
michael@0:   { $: suspect },
michael@0:   { $: validation }
michael@0: ).$
michael@0: 
michael@0: function Allow(script) ({
michael@0:   get script() script,
michael@0:   set script(value) script = !!value
michael@0: })
michael@0: 
michael@0: /**
michael@0:  * Trait is intended to be used in some composition. It provides set of core
michael@0:  * properties and bounded validations to them. Trait is useful for all the
michael@0:  * compositions providing high level APIs for interaction with content.
michael@0:  * Property changes emit `"propertyChange"` events on instances.
michael@0:  */
michael@0: const Loader = EventEmitter.compose({
michael@0:   /**
michael@0:    * Permissions for the content, with the following keys:
michael@0:    * @property {Object} [allow = { script: true }]
michael@0:    * @property {Boolean} [allow.script = true]
michael@0:    *    Whether or not to execute script in the content.  Defaults to true.
michael@0:    */
michael@0:   get allow() this._allow || (this._allow = Allow(true)),
michael@0:   set allow(value) this.allow.script = value && value.script,
michael@0:   _allow: null,
michael@0:   /**
michael@0:    * The content to load. Either a string of HTML or a URL.
michael@0:    * @type {String}
michael@0:    */
michael@0:   get contentURL() this._contentURL,
michael@0:   set contentURL(value) {
michael@0:     value = validate(value, valid.contentURL);
michael@0:     if (this._contentURL != value) {
michael@0:       this._emit('propertyChange', {
michael@0:         contentURL: this._contentURL = value
michael@0:       });
michael@0:     }
michael@0:   },
michael@0:   _contentURL: null,
michael@0:   /**
michael@0:    * When to load the content scripts.
michael@0:    * Possible values are "end" (default), which loads them once all page
michael@0:    * contents have been loaded, "ready", which loads them once DOM nodes are
michael@0:    * ready (ie like DOMContentLoaded event), and "start", which loads them once
michael@0:    * the `window` object for the page has been created, but before any scripts
michael@0:    * specified by the page have been loaded.
michael@0:    * Property change emits `propertyChange` event on instance with this key
michael@0:    * and new value.
michael@0:    * @type {'start'|'ready'|'end'}
michael@0:    */
michael@0:   get contentScriptWhen() this._contentScriptWhen,
michael@0:   set contentScriptWhen(value) {
michael@0:     value = validate(value, valid.contentScriptWhen);
michael@0:     if (value !== this._contentScriptWhen) {
michael@0:       this._emit('propertyChange', {
michael@0:         contentScriptWhen: this._contentScriptWhen = value
michael@0:       });
michael@0:     }
michael@0:   },
michael@0:   _contentScriptWhen: 'end',
michael@0:   /**
michael@0:    * Options avalaible from the content script as `self.options`.
michael@0:    * The value of options can be of any type (object, array, string, etc.)
michael@0:    * but only jsonable values will be available as frozen objects from the
michael@0:    * content script.
michael@0:    * Property change emits `propertyChange` event on instance with this key
michael@0:    * and new value.
michael@0:    * @type {Object}
michael@0:    */
michael@0:   get contentScriptOptions() this._contentScriptOptions,
michael@0:   set contentScriptOptions(value) this._contentScriptOptions = value,
michael@0:   _contentScriptOptions: null,
michael@0:   /**
michael@0:    * The URLs of content scripts.
michael@0:    * Property change emits `propertyChange` event on instance with this key
michael@0:    * and new value.
michael@0:    * @type {String[]}
michael@0:    */
michael@0:   get contentScriptFile() this._contentScriptFile,
michael@0:   set contentScriptFile(value) {
michael@0:     value = validate(value, valid.contentScriptFile);
michael@0:     if (value != this._contentScriptFile) {
michael@0:       this._emit('propertyChange', {
michael@0:         contentScriptFile: this._contentScriptFile = value
michael@0:       });
michael@0:     }
michael@0:   },
michael@0:   _contentScriptFile: null,
michael@0:   /**
michael@0:    * The texts of content script.
michael@0:    * Property change emits `propertyChange` event on instance with this key
michael@0:    * and new value.
michael@0:    * @type {String|undefined}
michael@0:    */
michael@0:   get contentScript() this._contentScript,
michael@0:   set contentScript(value) {
michael@0:     value = validate(value, valid.contentScript);
michael@0:     if (value != this._contentScript) {
michael@0:       this._emit('propertyChange', {
michael@0:         contentScript: this._contentScript = value
michael@0:       });
michael@0:     }
michael@0:   },
michael@0:   _contentScript: null
michael@0: });
michael@0: exports.Loader = Loader;
michael@0: 
michael@0: exports.contract = contract(valid);