Returns: boolean ⇒ True when at least one exact matching trigger is found.

Extends: BIND.BindInterfaceInit

BindInterfaces go through an optional 'PLACEHOLDER' state when code attempts to getBindInterface or bind an uninitialized interface.

Properties

• PLACEHOLDER boolean

  (INTERNAL) True when non-existant interface is loaded or bound to.

• name string

  Self-reflection, primarily for debugging.

• [mustBeNamed = true] boolean

  DEFAULT TRUE. When true, causes a TypeError to be thrown when attempting to bind anonymous functions.

• [freezeHandler = true] boolean

  HARDCODED TRUE. Prevents modification of the handler function. Setting this to false would allow in-situ replacement of bound function handles. If you have a practical use case for this please contact the CORE development team.

• [add] function

  add Additional processing when adding a binding. Can abort the process... by throwing an error :P

• [disable] function

  disable Additional processing when disabling bindings. Bindings are never deleted, only disabled - usually by setting runsRemaining to -1.

• [filter] BindFilter
• [execOnAdd] object

  (EXPERIMENT) Simulated execution args used during initial binding when execOnAdd is true. See BIND/bind options.to add/remove binds. Does it make more sense to allow unique simulated args on a per-bindExec basis instead? Feedback welcome.

• list Array.<Binding>
• addedAt DOMHighResTimeStamp
• [scopes] Object.<string, Array.<number>>

  (CONCEPT) for lookups? Could use code similar to EVENT add/disable bindings. Currently there is experimental scoping at the per-bind level.

Properties

• [mustBeNamed = true] boolean

  DEFAULT TRUE. When true, causes a TypeError to be thrown when attempting to bind anonymous functions.

• [freezeHandler = true] boolean

  HARDCODED TRUE. Prevents modification of the handler function. Setting this to false would allow in-situ replacement of bound function handles. If you have a practical use case for this please contact the CORE development team.

• [filter] BindFilter
• [add] function

  add Additional processing when adding a binding. Can abort the process... by throwing an error :P

• [disable] function

  disable Additional processing when disabling bindings. Bindings are never deleted, only disabled - usually by setting runsRemaining to -1.

Properties

• triggers Array.<string>

  Array of strings used by the bind execution filter BindFilter.

• [scope] Array.<string> | string

  (EXPERIMENT) secondary filtering layer, primarily intended for DOM based filtering, but who knows...

• handler function

  executed when triggers passes the bindExec filter. It is scoped to this object (this returns the current Binding).

• id number

  array ID, pretty much only useful for self removal.

• runsRemaining number

  Defaults to Infinity.

• stats object

  Ideally moved to an accessible dedicated stats module allowing custom reporting, as adding binds to the binds module seems like a terrible idea.

• stats.added DOMHighResTimeStamp

  Currently performance.now. Likely to change. See #165 Date.now() in STATS.

• stats.runs Array.<DOMHighResTimeStamp>

  Times run (get total via runs.length)

• [stats.disabled] DOMHighResTimeStamp

  Created when bind is deactivated successfully

Properties: boundInterface BindInterface

Implements: BindFilter

Returns: number ⇒ Bind's position in the target interface's queue (execution order when executing)

Returns: Array.<number> ⇒ Bind IDs

Returns: boolean ⇒ True if any bind was executed. This may change in the future to 'successful' calls only, feedback welcome!

Categories: BIND, devTools

Prior to instantiation bindings may be registered to 'placeholder' interfaces; When a placeholder is initialized by this function, all previously added bindings are re-processed to ensure validity.

Best Practices

• We recommend only a single interface is initialized per module to reduce complexity.
• When naming a new interface, you must be very specific to avoid potential conflicts with future potential PageDriver CORE generic interfaces.
• DON'T use the initalizer for accessing other interfaces, use getBindInterface instead.
• Unless complete external access is warranted, exporting interfaces is discouraged.

Returns: Array ⇒ Triggers, function name, total executions, time added, time disabled.

Categories: devTools

Returns: boolean ⇒ Only returns true when a bind is actually disabled, all other situations such as no bindings, or already being disabled returns false.

Optional target specific disable logic can abort this process. Note disabling a binding doesn't delete it, it sets runsRemaining to -1 and records the timestamp to stats.disabled.

Context class names:

• CANNOT begin with a hyphen (-). This character is used for negated contexts.
• MUST begin with an uppercase character (ex. 'A' not 'a'. 'Л' not 'л'. 'Đ' not 'đ') for differentiation from basic CSS classes. If your chosen programming locale doesn't have capitalization we recommend standardizing a basic latin script prefix (ex. CCログインする, CC로그인) across your project.
• CANNOT be a reserved name.

Valid examples:

• "Vendor" Basic Latin uppercase
• "Лидер" Cyrillic uppercase
• "Đặc_Quyền" Vietnamese uppercase with underscore
• "CCログインする" prefixed with uppercase latin script

Invalid examples:

• "-Vendor" starts with hyphen (use for negation)
• "vendor" starts lowercased
• "123User" starts with number, note as of 2025/1/1 this is not enforced programmatically given classes are not normally permitted to begin with numbers.

See isValidContextName for the runtime validation.

Properties

• state boolean
• added EpochTimeStamp
• [modified] EpochTimeStamp

Current reserved context names:

• Javascript - Always actived (activated during INIT). -Javascript is an alternative to <noscript> tags.
• Debug - Active when DEBUG module debugger is loaded.
• Kbd - Accessibility (a11y) helper, active when using keyboard-like controls.

Returns: Object.<ContextName, ContextState> ⇒ Returns an empty object when no provided contexts are valid.

Returns: Object.<ContextName, ContextState> ⇒ Returns an empty object when no provided contexts are valid.

Returns: Object.<ContextName, ContextState> ⇒ Returns an empty object when no provided contexts are valid.

Throws: Error ⇒ when no contexts are provided.

Used by on/off/toggle helpers.

Returns: boolean | Object.<ContextName, ContextState> ⇒ Boolean when only a single Context is provided.

Toggling an undefined Context creates it (in true state).

Example

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

Properties: mutation MutationRecord

Properties

• args MutationRecord
• meta object

  {attributeValue, addAttribute, delAttribute, addAttributeValue, delAttributeValue}

Implements: BindFilter

Returns true when unscoped, otherwise if there is a mutation target:

• if a childList with added nodes, ensure scope is within target
• if an attribute, ensure scope matches the attribute name
• all other circumstances return true (ex. characterData, which as of 2024/12/15 isn't implemented)

I leave it to philosophers to decide if this means we use a VDOM 🙊

Generates generates a table of contents from HTML heading tags, placed in the first located element with the .tableOfContents class.

Categories: DOM, renderer

Returns: boolean ⇒ True if element matches original state.

Used by DOM restorer to reduce mutations when restoring elements to their original state from saved fragments.

Returns: boolean ⇒ True when saved.

Returns: boolean ⇒ True when restored.

Replaces the target's children with a deep clone of the saved node.

If this fails to escape content it means the browser is vulnerable, which is both crazy AND not our problem!

Example

escape('<script type="module" src="evil.mjs"></script>');
// returns `&lt;script type="module" src="evil.mjs"&gt;&lt;/script&gt;`
escape('normal & usual');
// returns `normal &amp; usual`

Asynchronous and removes own script element after loading by default. This was written before the days of wide browser module support and import / import(). Deprecation or refactor is being considered if the benefits it provides are insufficient.

Categories: DOM, renderer

Non-object keys are matched to DOM elements via the following rules:

1. Elements with 'name' attribute:
   • Inexact key match via [name$="key"].
   • (When nested) Exact key match [name="parentKey[key]"] within nested arrays/objects.
2. Elements with any class names starting with pd_.
3. (EXPERIMENT) Class names directly matching the nested child object key's name (no 'pd_' required).

Default string, number, boolean type value mutations:

• <input> and <select> form fields (radio, checkbox, select).
• <time> add relative attribute to generate a relative locale time.
• <textarea> updates vertical sizing (may be moved out of CORE).
• All others element's content is replaced as PLAIN TEXT. When replacing a non-empty element, its INITIAL content (content not added by the populator) is retained. This content is restored on future calls with an empty string value, allowing for 'default content' in non-input elements. This MAY become a non-default boolean option in a future release - given feedback.

Categories: DOM hydrator, renderer, mutator

Returns: string ⇒ CSS selector string, ordered by CSS specificity.

Example

stringToSelector('fizz') → '#fizz,.pd_fizz,.fizz,[name$="fizz"],[data-fizz],[data-pd_template-key="fizz"],fizz'
stringToSelector('fizz','.buzz') → '#fizz.buzz,.pd_fizz.buzz,.fizz.buzz,[name$="fizz"].buzz,[data-fizz].buzz,[data-pd_template-key="fizz"].buzz,fizz.buzz'

Returns: string ⇒ Empty string when no useable attribute is found.

Example

<article id='reference'>...</article> // 'Reference'
<div id='user_profile-editor'>...</div> // 'User profile editor'
<div id="foo" data-name="returns as is!">...</div> // 'returns as is!'

Returns: Array.<HTMLElement> ⇒ Couldn't this be any Element?

Creates a new element if no matching style element exists.

Categories: DOM, CSS, loader, mutator

Useful UX Helper that can be used to temporarily add animation classes, disabling buttons, etc.

Categories: DOM, mutation, temporal

Properties

• shadowTarget Element

  Populated with true target when an Event targets an element within an open shadowRoot (via composedPath()[0]).

• pd_cascade boolean

  Forces EVENT filter to treat a simulated event as real, which may trigger others.

Properties

• isKbd boolean

  Is this a keyboard-like event?

  • true for KeyboardEvent
  • false for MouseEvent and TouchEvent
  • null for all other events EXCEPT FocusEvent, where it retains its previous state.
• priorEvents Array.<module:EVENT~PDEvent>

  Previously captured events (currently hardcoded as 10).

• lastEventTrusted boolean

  Browser native event.isTrusted is untrustworthy, use this instead!

  For whatever reason event.isTrusted becomes true when:

  • a new MouseEvent is dispatched without an eventInitDict parameter. It becomes trusted after dispatch! This may be true for other artificially created events as well.
  • Follow-up events (such as input/change) on untrusted form input click events become trusted.

  Please see this CodePen for demonstration. Reach out to core team if this is a known "wontfix", or are working on an eventual solution allowing us to remove it.

• activeListeners Array.<string>

  Array of active DOM event types with listeners added via bindAdded to document, which call pd.EVENT.handler.

• notices

  State container for one-off developer warnings and notices.

See module for logic description.

Returns: string ⇒ escaped CSS

Categories: helper, devTools

Returns: string ⇒ Unicode regional indicator symbol

Example

ca → 🇨🇦
de → 🇩🇪
cn → 🇨🇳

Categories: helper, emoji, string, transformer, unicode

Returns: string | false ⇒ false when date is malformed

Modified version of Kyle Cook's formatter.

Returns: Promise.<(Object|function())> ⇒ import() promise returns requested function or module (object) on success.

Throws: Error ⇒ Throws outside 'Development' environment.

This module has no exports, it creates the iL() function under globalThis.

• Multiple exports: module is assigned.
• Single export: single export assigned.

Example

iL('HELPER/slugify.mjs'); // Loads single export module as `slugify()`.
iL('dom/elements.mjs'); // Loads multiple export module as `elements` module.

Categories: devTools, helper

Returns: object ⇒ New object with merged key/values

Doesn't modify objects (immutable) and merges arrays via concatenation. Consider an alternative for advanced merges.

Returns: number ⇒ Integer hash (currently CRC24)

Using this for cryptography will result in being shot from a cannon into low earth orbit ✨🌎 (don't use this for cryptographic purposes).

Categories: helper

Normally used for URL paths and link anchors.

Example

slugify('Hello World!') // 'hello-world'
slugify('Café & Restaurant') // 'cafe-restaurant'
slugify('Multiple   Spaces') // 'multiple-spaces'
slugify('--Leading-and-trailing--') // 'leading-and-trailing'
slugify('Hello World', { separator: '_' }) // 'hello_world'
slugify('Hello World', { lowercase: false }) // 'Hello-World'

Categories: helper, string, transformer

Returns: boolean ⇒ true on success, false when no #modals element is located in the document.

Throws: ReferenceError ⇒ When requested modal element doesn't exist.

Modals are contained within an element with the #modals ID.

Returns: boolean ⇒ false when no modals exists, no modal is active, or if the modal cannot be closed without force.

This function only closes modals whose first child is a closeBtn button unless the force parameter is true, otherwise the element temporarily gains the attention class. This allows non-critical modals to be closed by pressing on the backdrop.

Only one modal is active at any given time (assuming nothing broke).

Returns: Object.<string, string> | Object ⇒ Empty object when no header values are returned.

Returns: boolean ⇒ True if path is considered local, false otherwise.

Throws: TypeError ⇒ When src is not a string.

Returns false when src string begins with a protocol UNLESS it exactly matches window.location.origin.

Example

// Assuming origin is https://example.com

// Returns true
isLocalPath('/foo');
isLocalPath('foo.com');
isLocalPath('bar.php');
isLocalPath('foo/bar?fizz#buzz');
isLocalPath('https://example.com');
isLocalPath('https://example.com/foo');
isLocalPath('//example.com');  // `//` matches current protocol, how useful!

// Returns false
isLocalPath('http://example.com');  // mismatched protocol
isLocalPath('https://example.com.evil.org/foo');  // mismatched origin
isLocalPath('javascript:alert("evil")');  // non-http protocol

Returns: XMLHttpRequest ⇒ passes responseObj, src URL to provided callback

• Automatically applies pd-csrf and pd-app-version headers to local requests.
• Under Development ENV the noStore option is true on all local requests to ensure freshness. Create a cookie named pd-debug-breakLocalCache to disable this feature.

Why XHR and not Fetch?

• Fetch doesn't track upload progress natively
• Once timeouts, abort controls and other features are added, Fetch feels about the same.
• It's what I knew best when writing PageDriver, feel free to contribute a PR, especially once work begins on ServiceWorkers!

body>main, body>#main, body>#pages.

• When successful, the active class is added to the requested page element, the document title, meta description and meta keywords are updated.
• entering helper class is temporarily added to the current page element, exiting on the previously active page, if any.
• When not permitted (due to context class or inaddequate permissions), the index ID page is activated.
• (EXPERIMENTAL) When not found, the error-404 ID page is activated. Mutates errorMsg.
• (EXPERIMENTAL) When a critical error happens during APP initiation , the error-critical ID page is activated. Mutates errorMsg.
• (EXPERIMENTAL) Pages with the unloaded class are remote. xhr attempts loading it from /pages/ router, which (if successful) calls this function again, replacing element's content and the unloaded class with remote. This requires server-side framework features.

Only one page should be active at any given time, thus this only returns the first result. An active page is any direct descendant of the project's page container with the active class.

Properties

• env 'Development' | 'Production'

  Environment.

• [perf] boolean

  Enables PageDriver performance monitoring outside 'Debug' mode.

• contexts Array.<string>

  Context classes / flags

• [domain = window.location.hostname] string

  Automatically created during project init.

• [path = /] string

  This instance's root path.

• api string

  API URI, prepended to local API requests.

• title string

  Site title.

• siteTitleFirst boolean

  Site title appears first, useful for RTL.

• [titleDivider = ·] string

  site and page title separator in window title.

• header HTMLElement

  First found header or #header element.

• primaryNav HTMLElement

  First found nav , #nav or #menu element.

• mainRegion HTMLElement

  Primary content region (body>#main , body>main).

• fixedScroll boolean

  Does the pages element have fixed scrolling? Is scrolling controlled by pd.SITE.pages element or window?

• pages HTMLCollection

  #pages children.

• modals HTMLCollection

  #modals children.

• [remoteReporting] object

  Project's reporting/logging provider. Initialized under 'Production' environment. Create an empty 'pd-forceLogging' cookie to force remote logging outside 'Production' environment. Only Sentry.io is supported at this time.

• remoteReporting.endpoint URI

  Provider's reporting endpoint

• remoteReporting.src URI

  Provider's bundle location

• [remoteReporting.integrity] string

  Subresource Integrity (SRI) hash, may be required by your CORS settings.

• [remoteReporting.initExtras] object

  Optional properties added to the provider's init. Warning: This can override hardcoded PD options.

• [description] string

  Default site-wide meta tag. Used when none available at page level.

• [keywords] string

  Default site meta tag.

The following is out of date, eventually this list will be automatically rendered from inline @steps:

1. Debug state check, when the debug cookie is present load and initialize debug tools.
2. Begin performance measurement (when enabled).
   • 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. Logging 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

Returns: string | null ⇒ Mark ID or null.

Only functions if device has the performance API, pd.SITE.perfMark is true OR Debug mode is enabled.

Example

returns `0.8128820578073859` for 'FOO INIT-0.8128820578073859' performance mark.

Returns: number | null ⇒ seconds, rounded to 2 decimal places. null on devices without performance API or with perfMark disabled.

Measurement only outputs console messages when:

• the verbose perfMark debug flag is active
• AND when the measurement is above 3 significant digits (to reduce console spam).

Returns: string | boolean ⇒ Returns false boolean when non-existent. Returns boolean existence argument is true. Otherwise returns cookie contents string.

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

Categories: DOM, UI

Returns: number ⇒ Total activated elements.

This function finds elements with data-re attributes corresponding to the target's name and value, then activates matching elements while deactivating others.

1. Potential follow up elements are located via the data-re dataset attribute, with a value of the target's name attribute, followed by an underscore [data-re="nameAttr_"].
2. Elements exactly matching [data-re="nameAttr_valueAttr"] and/or [data-re="nameAttr__ANY"] are given the active CSS class.
3. The active CSS class is removed from non-matching elements.
4. When no exact matches are activated, elements matching [data-re="nameAttr__NONE"] are given the active CSS class. The double underscore is intentional to reduce value collision chance.

Examples:

• Target: <input name="eventVis" value="public"> - Elements with the attribute data-re="eventVis_public" add the active CSS class, whilst all other elements data attributes starting with eventVis_ (such as eventVis_private) have the class removed.
• <option value="0"> - The 'name' attribute of a parent <select> is found with the value 'partySize'. No elements with the attribute data-re="partySize_0" were found, so elements with the data-re="partySize__NONE" add the active CSS class, whilst all other elements with re data classes starting with partySize_ have the active class removed.
• (see warning below!) <input type="checkbox" name="noValue"> - Because this input has no value, it will activate elements with data-re="noValue_on"
• (see warning below!) <option>foobar</option> - Because this input has no value, it will activate elements with data-re="noValue_foobar"

Categories: UI, CSS

Categories: UI, notification, template

// TODO externalized to module? // TODO Output as --pd-textarea-height to allow custom styling?

Returns: boolean ⇒ True when closed via local storage

Categories: UI

Returns: number ⇒ Interval ID when activated. Null when element invalid or expired datetime.

appear class temporarily applied to the element on activation. Mutation interval is exactly 1 second.

Properties

• dateTime dateString

  Future date/time. Accepts anything new Date() would.

• [el = '#countdown'] HTMLElement

  Defaults to 'countdown' ID element.

• [completedClass = 'complete'] string

  Completed CSS class is added when timer expires OR an invalid date is provided.

Categories: UI, timer

Returns: number ⇒ Current pending operations. Cannot be less than 0.

Modifies the --counter variable on the spinner element which can be used to not only hide/reveal the element itself, but dynamically adjust UX - such as the spinner's animation speed.

Categories: UI, DOM