Any object may have a bind queue, but only the object itself should execute them. Currently we don't prevent remote bind execution, however prevention may be enforced in the future.

Binds allow the creation of interface-like structures.

// Sample containing a single binding
SAMPLE_INTERFACE:{
	name:'SAMPLE_INTERFACE',
	boundTo:null,
	mustBeNamed:true,
	boundAt:null,
	createdAt:79.29999,
	scopes:{
		'#sampleID':[0],
		'.sampleClass':[0],
	},
	list:[{
		id:0,
		runsRemaining:Infinity,
		scope:['#sample','.sample'],
		triggers:['click'],
		handler:()=>{ console.log('hello world'); },
		_STATS:{
			runs:[123],
			added:performance.now(),
			disabled:null,
		},
	}],
};

They are used to toggle common project elements relevant to different personas. For example, elements meant for a regular user, moderator, or manager. See ContextName for naming rules.

contextToggle('Foo'); // Returns a boolean
contextToggle(['Foo','Bar']); // Returns { ContextState, ... }

Adding your own verbose flags is as simple as if (pd.DEBUG && pd.DEBUG.verbose.myCodeFlag) console.log('foo!'), no additional code required. Please be mindful as there are no 'reserved' flags or groups (yet), so ensure both:

• your output is as specific as possible to a particular flag, or set of flags.
• the verbose flag property name is specific enough.

This module only supports a single active observer for no real reason, although performance and coder sanity are a good excuse as any.

The following is likely out of date, eventually this list will be automatically rendered based on inline @step and @stepOpts:

1. Start performance measurement
2. Debug state check, when debug cookie is present load and initialize debug tools.
   • Otherwise, execute optional app.notDebugging() function (to do things such as displaying a default console message/warning)
3. Setup remote logging. If pd.SITE.ENV is Production, initialize logger based on pd.SITE.remoteReporting object. Can be forcibly enabled via forceLogging cookie in other environments
4. Set pd.SITE DOM references and booleans
5. Context class setup
6. i18n initialization
7. pd.DOM elements (most removed for upcoming modularity)
   • closeable
8. Attempt initializing app.js via app.INIT() (/w perf measurement)
9. pd.SITE.location
10. End performance measurement
11. Destroy pd.INIT

Code reviewers

• Too much to take in? Search for comment flags (see ## COMMENT FLAGS below) containing question marks instead and skip to those :p
• Try not to focus on:
  • swappable/toggleFUQs/selected fns. Being refactored (see issue #16, #205)
  • closeables (along with a bunch of other INIT run-once features) will be refactored to use a bindable mutation observer
  • External settings (pd.SITE etc) are currently generated server side. Ideally they'll be compiled to a mostly static (JSON?) file. To be finalize this by next milestone... advice appreciated.

PageDriver was created to solve the following pain points

• Too much damn boilerplate, keep code coherent and clean.
• Bring back some separation of concerns (HTML/CSS/JS). They can be in the same file as part of simple single-file components, but not so intermingled.
• Callback hell, solved by 'bind' buses (bus maybe the wrong term?)
• Minimize and clean call stack to assist in debugging.
• DOM hydration concerns, I want it to follow state on demand!
• Lack of accessibility. A11y is normally out-of-scope for small to medium sized projects, I want to change that.
• Requiring a virtual DOM. It does have a use case for repeating elements scrolling outside the viewport (such as tables). I've done testing and it's unnecessary for the majority of projects. Let's keep things close to vanilla!

Contributor's guide

• Please review https://gitlab.com/evilumb/pagedriver/dev/-/issues/125
• If you're reading this, you should join our #development Discord channel!
• Useful daily references: MDN Web Docs, Regex101, Can I Use, HTML symbols

CODE COMMENT GUIDE

• Negations MUST BE contractions for comprehension and specificity. They MUST be capitalized if critical. Examples: "don't" vs "do not", "won't" vs "will not", "can't" vs "can not" (although "cannot" is OK!)
• Append relevant repo issue #s, if at all possible.
• @warning must begin with a date (YYYY/MM/DD) to be checked for continued relevance

COMMENT FLAGS

• Highlight flags in VSC via 'gruntfuggly.todo-tree' extension. Project settings are included in the repo.
• WIP for code that is a work in progress and likely broken. Don't commit these.
• i18n for marking strings requiring translation.
• SETTINGS for variables eventually managed by project admin/super-admin.
• BIND for marking areas with 3rd-party extendability (usually bindExec)
• Once stable, code containing WIP, FIXME and TODO comment flags will be automatically rejected.

CORE DEVELOPER COMMENT FLAGS (don't commit these unless you're a CORE dev)

• Add FIXMEs to critical, high priority code that you are unable to fix yourself. FIXME code CANNOT be submitted for stable releases!
• TODO are low priority FIXMEs with an assigned issue (create one if none exists), and may exist in stable releases. These are a temporary measure from initial development efforts.
• DOC for marking areas requiring external documentation from the documentation team. NOT an alternative to commenting your code.

CORE CODE GUIDE (oldest first)

• 2020/04/25 [Consistency] 'use strict'; outside ESM modules
• 2020/04/25 [Compatibility] When using native features, they MUST pass the project's CIU threshold (currently ~95%)*. See https://gitlab.com/evilumb/pagedriver/dev/-/issues/66 for more details
• 2020/04/25 [Consistency] Iterate HTMLCollections with bracket notation [i], not .item(i) method
• 2020/04/25 FUTURE DEPRECIATION: Many PageDriver settings are set via project index's state initializer file, this will be improved. #162
• 2020/04/25 [Mutation] use document.createDocumentFragment(); when the primary objective is reducing total DOM mutations, otherwise measure actual performance, prioritizing code readability.
• 2020/04/25 [Performance] requestAnimationFrame() can force unnecessary re-rendering, most circumstances do not require it.
• 2021/02/09 [Consistency] Use Object.assign() instead of spread operator where possible. Spread is 93.05% CIU, 1% slower, and doesn't improve code readability that much.
• 2021/03/10 [Documentation] Using Regex? Register at https://regex101.com, and provide a link in code commentary along with some match/non-matching samples if possible.
• 2021/04/03 [Mutation] When directly adding/removing CSS classes, they trigger class attribute mutation even if nothing actually changes (per spec). Use pd.DOM class helpers or check classlist.contains first if mutation is an issue (pd.OBSERVER may ignore these in the future).
• 2021/04/06 [Consistency] options={} for parameter options, then Object.assign() defaults to params obj internally. Once spread operator passes CIU %, codebase may transition to it. Use deep merge helper for options with complicated nested defaults (although that might be a code smell). JSDOC options props, not params props.
• 2021/05/03 [Consistency] Object literals > classes. Why? Lorin likes em'. ¯\_(ツ)_/¯
• 2022/03/24 [Consistency] Use provided function names instead of local destructuring, to prevent core code bloat.
• 2022/09/19 [Consistency] Modules exporting single default functions are preferred, however when exporting objects containing a set of functions, the file and module name MUST BE capitalized for easy identification and potential future splitting for improved tree-shaking.
• Take care iterating HTMLCollections by index if elements are being removed within the loop, as HTML DOM is live!

HINTS

• [Performance] Short circuit, break early when possible. "The cheapest function call is the one you never make" - Jason Miller, Preact dev.
• 2022/08/30 [Performance] Converting NodeLists to Array is SLOW. Array.from is slower than spread.
• 2021/05/03 [DevTools] Alert() is for chumps. Try live expressions, breakpoints, debugger;, or console.log(). See additional helpful utilities here https://developer.chrome.com/docs/devtools/console/utilities/?utm_source=pagedriver&utm_medium=sourcecode
• 2021/02/16 [Annoyance] HTMLElement.prototype.closest doesn't accept other HTMLElements, just a selector string :|
• 2021/04/06 [Annoyance] Don't trust event.isTrusted, see notes in pd.EVENT.simulate.

Returns: boolean ⇒ True when closed via local storage

Prepend navigation button for collapsing primary navigation on small devices (hamburger 🍔)