@nent/core
Version:
1,269 lines (1,268 loc) • 197 kB
JSON
{
"timestamp": "2022-08-09T16:38:41",
"compiler": {
"name": "@stencil/core",
"version": "2.17.3",
"typescriptVersion": "4.5.4"
},
"components": [
{
"filePath": "./src/components/n-action/action.tsx",
"encapsulation": "none",
"tag": "n-action",
"readme": "# N-ACTION\n\nThis element holds am action event and its data to be submitted through [Actions](/actions) bus. The parent tag defines how and when the child actions are submitted through [Actions](/actions). \n\n> ℹ️ This element does not activate these actions automatically. They need to be activated through script, or by wrapping them in an [`n-action-activator`](/components/n-action-activator) tag.\n\n\n## Element\n\n```html\n<n-action \n topic='<topic>'\n command='<command>'\n data-(key)='value'>\n</n-action>\n```\n",
"docs": "This element just holds data to express the actionEvent to fire. This element\nshould always be the child of an n-action-activator.",
"docsTags": [
{
"name": "system",
"text": "actions"
}
],
"usage": {
"basic": "\nFor most action-argument data, it is easiest to specify them as key-value pairs using the `data-*` attributes within the `n-action` tag. The name of the argument should be prefixed with `data-`. A\n\n```html\n<n-action topic='<topic>'\n command='<command>'\n data-(key)='value'>\n</n-action>\n```\n\n> ℹ️ Note: If a listener declares an argument using 'camelCase', it should be converted to 'kebab-case' in HTML, (words separated by dashes, all lowercase). It will be converted to 'camelCase' automatically when activated.\n\n\n#### Real example\n\n```html\n<n-action topic='navigation'\n command='go-to'\n data-path='/some/path'>\n</n-action>\n```\n",
"conditional": "To add a condition to your actions, add a when attribute to the action element with your predicate expression.\n\n```html\n<n-action topic='<topic>'\n command='<command>'\n when='<expression>'\n data-(key)='value'>\n</n-action>\n...\n<n-data></n-data>\n```\n\n> ℹ️ Note: You must enable data services, by adding an `n-data` element to the page.\n\n\n#### Real example\n\n```html\n<n-action topic='navigation'\n command='go-to'\n when='{{storage:auto-navigate}}'\n data-path='/some/path'>\n</n-action>\n```\n",
"input data": "\nFor most data, it is easy to specify key-value pairs using the `data-*` attributes within the `n-action` tag.\n\n```html\n<n-action topic='<topic>'\n command='<command>'>\n <input type='hidden'\n name='arg1'\n value='Hello World'>\n</n-action>\n```",
"script data": "\nFor more complex data shapes, you can define the data parameters as JSON in a child script tag.\n\n```html\n<n-action topic='<topic>' command='<command>'>\n <script type='application/json'>\n {\n 'arg1': 'Hello world!'\n }\n </script>\n</n-action>\n```",
"tokens": "\nIf the `n-data` extension is enabled, you can use token-expressions as the value for actions:\n\n```html\n<n-action \n topic='<topic>'\n command='<command>'\n data-(key)='{{provider:key}}'>\n</n-action>\n```\n"
},
"props": [
{
"name": "command",
"type": "string",
"mutable": false,
"attr": "command",
"reflectToAttr": false,
"docs": "The command to execute.",
"docsTags": [],
"values": [
{
"type": "string"
}
],
"optional": false,
"required": true
},
{
"name": "topic",
"type": "string",
"mutable": false,
"attr": "topic",
"reflectToAttr": false,
"docs": "This is the topic this action-command is targeting.",
"docsTags": [],
"values": [
{
"type": "string"
}
],
"optional": false,
"required": true
},
{
"name": "when",
"type": "string | undefined",
"mutable": false,
"attr": "when",
"reflectToAttr": false,
"docs": "A predicate to evaluate prior to sending the action.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
}
],
"methods": [
{
"name": "getAction",
"returns": {
"type": "Promise<EventAction<any> | null>",
"docs": ""
},
"signature": "getAction() => Promise<EventAction<any> | null>",
"parameters": [],
"docs": "Get the underlying actionEvent instance. Used by the n-action-activator element.",
"docsTags": []
},
{
"name": "sendAction",
"returns": {
"type": "Promise<void>",
"docs": ""
},
"signature": "sendAction(data?: Record<string, any> | undefined) => Promise<void>",
"parameters": [],
"docs": "Send this action to the action messaging system.",
"docsTags": []
}
],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-action-activator/action-activator.tsx",
"encapsulation": "none",
"tag": "n-action-activator",
"readme": "# N-ACTION-ACTIVATOR\n\nThis element defines how and when a group of Actions, defined with the [`n-action`](/components/n-action) element, are submitted through the [actions system](/actions).\n\nThis element should only ever contain child [`n-action`](/components/n-action) tags. The attributes defines how and when the child-actions are submitted through the [actions system](/actions).\n\n```html\n<n-action-activator\n activate='<activation-strategy>'\n ...\n supporting\n attributes\n ...\n>\n <n-action ...></n-action>\n <n-action ...></n-action>\n <n-action ...></n-action>\n</n-action-activator>\n```\n\n## Activation Strategies\n\nThe **activate** attribute defines the strategy for activating all child actions in the order they appear.\n\n### `on-element-event`\n\nThe default strategy is `on-element-event` which can be used anywhere. The child-actions will fire when the target element raises the target event.\n\n### `on-enter`\n\nActivation occurs when the parent route is activated and the contents are displayed.\n\n### `on-exit`\n\nActivation occurs when the parent route is de-activated and the next route is displayed.\n\n### `on-render`\n\nActivation occurs when the parent element is displayed.\n\n### `at-time`\n\nActivation occurs when the parent route has been activated for the given time within the **time** attribute.\n\n### `at-time-end`\n\nActivation occurs when the presentation ends.\n",
"docs": "This element defines how or when a group of actions are\nactivated. The actions activated must be included between\nthis elements tags.",
"docsTags": [
{
"name": "system",
"text": "actions"
}
],
"usage": {
"on-element-event": "### On Element Event\n\nThe default activation is OnElementEvent and the default event is click. Also, if no target-element is supplied, it looks for the first element that isn't an action or script and attaches to its event. If no target-event is defined, it assumes 'click'\n\n```html\n<n-action-activator>\n <n-action ...></n-action>\n <n-action ...></n-action>\n <n-action ...></n-action>\n <button>Click Me</button>\n</n-action-activator>\n```\n\n> ℹ️ Note: _PRO-TIP:_ This element appends any child input element's values to the actions it fires.",
"on-enter": "### On Enter\n\n```html\n<n-view-prompt ...>\n <n-action-activator activate='on-enter'>\n <n-action ...></n-action>\n <n-action ...></n-action>\n <n-action ...></n-action>\n </n-action-activator>\n</n-view-prompt>\n```\n\n> ℹ️ Note: The `on-enter` activation-strategy only works when this element is a child of [`n-view`](/components/n-view) or [`n-view-prompt`](/components/n-view-prompt).\n",
"on-exit": "### On Exit\n\n\n```html\n<n-view-prompt ...>\n <n-action-activator activate='on-exit'>\n <n-action ...></n-action>\n <n-action ...></n-action>\n <n-action ...></n-action>\n </n-action-activator>\n</n-view-prompt>\n```\n\n> ℹ️ Note: The `on-exit` activation-strategy only works when this element is a child of [`n-view`](/components/n-view) or [`n-view-prompt`](/components/n-view-prompt).\n",
"on-render": "### On Render\n\nThis activation-strategy fires as soon as the activator component renders. It can be pulled in through remote templates or added to a page for analytics.\n\n```html\n<n-action-activator activate='on-render'>\n <n-action ...></n-action>\n <n-action ...></n-action>\n <n-action ...></n-action>\n</n-action-activator>\n```\n\n> ℹ️ Note: The `on-exit` activation-strategy only works when this element is a child of [`n-view`](/components/n-view) or [`n-view-prompt`](/components/n-view-prompt).\n",
"presentation-at-time": "### At Time\n\nActivation occurs when the presentation has been playing for the given time within the **time** attribute.\n\n```html\n<n-presentation>\n <n-presentation-timer duration=\"3\">\n </n-presentation-timer>\n <n-action-activator \n activate='AtTime' \n time='3'>\n <n-action ...></n-action>\n <n-action ...></n-action>\n </n-action-activator>\n</n-presentation>\n```\n\n> ℹ️ Note: The `at-time` activation-strategy only works when this element is a child of [`n-presentation`](/components/n-presentation).\n",
"presentation-at-time-end": "#### At Time End\n> ℹ️ Note: The `at-time=end` activation-strategy only works when this element is a child of [`n-presentation`](/components/n-presentation).\n\n```html\n\n<n-presentation>\n <n-video ...>\n </n-video>\n <n-action-activator activate='AtTime' \n time='3'>\n <n-action ...></n-action>\n <n-action ...></n-action>\n </n-action-activator>\n</n-presentation>\n\n> ℹ️ Note: For more information on presentation and how they work, see [`n-presentation`](/components/n-presentation)"
},
"props": [
{
"name": "activate",
"type": "\"at-time\" | \"at-time-end\" | \"on-element-event\" | \"on-enter\" | \"on-exit\" | \"on-render\"",
"mutable": false,
"attr": "activate",
"reflectToAttr": false,
"docs": "The activation strategy to use for the contained actions.",
"docsTags": [],
"default": "'on-element-event'",
"values": [
{
"value": "at-time",
"type": "string"
},
{
"value": "at-time-end",
"type": "string"
},
{
"value": "on-element-event",
"type": "string"
},
{
"value": "on-enter",
"type": "string"
},
{
"value": "on-exit",
"type": "string"
},
{
"value": "on-render",
"type": "string"
}
],
"optional": false,
"required": false
},
{
"name": "debug",
"type": "boolean",
"mutable": false,
"attr": "debug",
"reflectToAttr": false,
"docs": "Turn on debug statements for load, update and render events.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "once",
"type": "boolean",
"mutable": false,
"attr": "once",
"reflectToAttr": false,
"docs": "Limit the activation to ONCE. This could be helpful if an action\nhas side-effects if it is run multiple times.\n\nNote: the activation\nstate is stored in memory and does not persist across refreshes.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "targetElement",
"type": "string | undefined",
"mutable": false,
"attr": "target-element",
"reflectToAttr": false,
"docs": "The element or elements to watch for events when using the OnElementEvent\nactivation strategy. This element uses the HTML Element querySelectorAll\nfunction to find the element/s based on the query in this attribute.\n\nIf left blank, this element looks for child elements matching:\n'a,button,input[type=button]'\n\nFor use with activate=\"on-element-event\" and \"at-time\"",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "targetEvent",
"type": "string",
"mutable": false,
"attr": "target-event",
"reflectToAttr": false,
"docs": "This is the name of the event/s to listen to on the target element\nseparated by comma.",
"docsTags": [],
"default": "'click,keydown'",
"values": [
{
"type": "string"
}
],
"optional": false,
"required": false
},
{
"name": "time",
"type": "number | undefined",
"mutable": false,
"attr": "time",
"reflectToAttr": false,
"docs": "The time, in seconds at which the contained actions should be submitted.\n\nFor use with activate=\"at-time\" Only!",
"docsTags": [],
"values": [
{
"type": "number"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
}
],
"methods": [
{
"name": "activateActions",
"returns": {
"type": "Promise<void>",
"docs": ""
},
"signature": "activateActions(once?: boolean) => Promise<void>",
"parameters": [],
"docs": "Manually activate all actions within this activator.",
"docsTags": []
}
],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-app/app.tsx",
"encapsulation": "none",
"tag": "n-app",
"readme": "# N-APP\n\nThis element enables application installation features for progressive web applications.\n\nIt also handles event/action delegation between the HTML DOM and NENT bus.\n\nAdditionally, this element is required to add external elements that need to be activated using actions.\n\n## Element Description\n\n```html\n<n-app\n name=\"\"\n description=\"\" \n keywords=\"\"\n short-name=\"\"\n icon-src=\"\"\n theme-color=\"\"\n background-color=\"\"\n \n disable-manifest\n disable-meta-tags\n disable-actions\n debug>\n</n-app>\n```\n\n",
"docs": "This component enables app services. These are console logging,\ntheming and event-delegation. As well as a plugin system to\nmanage a UI kit to add components like Modals, Drawers,\nmenus, etc.",
"docsTags": [
{
"name": "system",
"text": "app"
},
{
"name": "extension",
"text": "actions"
},
{
"name": "extension",
"text": "custom"
},
{
"name": "extension",
"text": "elements"
}
],
"usage": {
"basic": "```html\n<n-app id=\"app\"\n app-title=\"NENT\"\n app-description=\"Functional elements to super-charge your HTML\"\n app-keywords=\"web-components, low-code, no-framework, jam-stack, nent\">\n ...\n</n-app\n```"
},
"props": [
{
"name": "appDescription",
"type": "string | undefined",
"mutable": false,
"attr": "app-description",
"reflectToAttr": false,
"docs": "This is the application default page description.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "appKeywords",
"type": "string | undefined",
"mutable": false,
"attr": "app-keywords",
"reflectToAttr": false,
"docs": "This is the application default page keywords.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "appTitle",
"type": "string | undefined",
"mutable": false,
"attr": "app-title",
"reflectToAttr": false,
"docs": "This is the application / site title.\nIf the views have titles,\nthis is added as a suffix.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "debug",
"type": "boolean",
"mutable": false,
"attr": "debug",
"reflectToAttr": false,
"docs": "Turn on debugging to get helpful messages from the\napp, routing, data and action systems.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
}
],
"methods": [],
"events": [
{
"event": "nent:actions",
"detail": "any",
"bubbles": false,
"cancelable": true,
"composed": true,
"docs": "These events are command-requests for action handlers to perform tasks.\nAny outside handlers should cancel the event.",
"docsTags": []
},
{
"event": "nent:events",
"detail": "any",
"bubbles": true,
"cancelable": false,
"composed": true,
"docs": "Listen for events that occurred within the nent event system.",
"docsTags": []
}
],
"listeners": [
{
"event": "nent:actions",
"target": "body",
"capture": false,
"passive": true
}
],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-app-analytics/app-analytics.tsx",
"encapsulation": "none",
"tag": "n-app-analytics",
"readme": "# N-APP-ANALYTICS\n\nThe [`n-app-analytics`](/components/n-app-analytics) element delegates internal analytics commands to DOM events\nallowing developers to connect events to any analytics provider.\n\n## Actions\n\nThis element can respond to actions. See the [actions](/components/n-app-analytics/actions) documentation for more information.\n\n",
"docs": "This element serves as a proxy to delegate event-based\nfunctions to be consumed by various analytics snippets.",
"docsTags": [
{
"name": "system",
"text": "app"
},
{
"name": "extension",
"text": "actions"
}
],
"usage": {
"GTM": "\n\n```html\n<head>\n <!-- Global site tag (gtag.js) - Google Analytics -->\n <script\n async\n src='https://www.googletagmanager.com/gtag/js?id=G-ZZZ'\n ></script>\n <script>\n window.dataLayer = window.dataLayer || []\n function gtag() {\n dataLayer.push(arguments)\n }\n gtag('js', new Date())\n gtag('config', 'G-ZZZZ')\n </script>\n</head>\n<body>\n ...\n <n-app-analytics id='analytics'>\n <script>\n analytics.addEventListener( 'custom-event', ( e ) => {\n console.log(`event: ${JSON.stringify(e.detail)}`)\n Object.getOwnPropertyNames(e.detail).forEach(n => {\n gtag( n, e.detail[n] )\n console.debug(`gtag('${n}', '${e.detail[n]})'`)\n })\n } )\n analytics.addEventListener('page-view', e => {\n console.log(`event: ${JSON.stringify(e.detail)}`)\n gtag('page_view', e.detail.pathname)\n })\n analytics.addEventListener('view-time', e => {\n console.log(`event: ${JSON.stringify(e.detail)}`)\n gtag(e.detail.key, e.detail.value)\n })\n </script>\n </n-app-analytics>\n</body>\n```",
"basic": "\nUsing the [`n-app-analytics`](/components/n-app-analytics) element is simple, but does require some scripting."
},
"props": [
{
"name": "debug",
"type": "boolean",
"mutable": false,
"attr": "debug",
"reflectToAttr": false,
"docs": "Turn on debugging to get helpful messages from the\napp, routing, data and action systems.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
}
],
"methods": [],
"events": [
{
"event": "custom-event",
"detail": "any",
"bubbles": true,
"cancelable": false,
"composed": false,
"docs": "Raised analytics events.",
"docsTags": []
},
{
"event": "page-view",
"detail": "LocationSegments",
"bubbles": true,
"cancelable": false,
"composed": false,
"docs": "Page views.",
"docsTags": []
},
{
"event": "view-time",
"detail": "ViewTime",
"bubbles": true,
"cancelable": false,
"composed": false,
"docs": "View percentage views.",
"docsTags": []
}
],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-app-share/app-share.tsx",
"encapsulation": "shadow",
"tag": "n-app-share",
"readme": "# N-APP-SHARE\n\nThe `<n-app-share>` element description\n\n",
"docs": "This element leverages the browser's web-share\nAPI to give the application a native-app feel.",
"docsTags": [
{
"name": "system",
"text": "app"
}
],
"usage": {
"basic": "Using the `<n-app-share>` element.\n\n```html\n<n-app-share \n headline=\"\"\n url=\"\"\n text=\"\">\n</n-app-share>\n```\n"
},
"props": [
{
"name": "headline",
"type": "string | undefined",
"mutable": false,
"attr": "headline",
"reflectToAttr": false,
"docs": "Headline for the share",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "text",
"type": "string | undefined",
"mutable": false,
"attr": "text",
"reflectToAttr": false,
"docs": "The textual body of web share",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "url",
"type": "string | undefined",
"mutable": true,
"attr": "url",
"reflectToAttr": false,
"docs": "The URL we are sharing",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
}
],
"methods": [
{
"name": "share",
"returns": {
"type": "Promise<void>",
"docs": ""
},
"signature": "share(data?: { title?: string | undefined; text?: string | undefined; url?: string | undefined; } | null | undefined) => Promise<void>",
"parameters": [],
"docs": "Manual share method for more complex scenarios",
"docsTags": [
{
"name": "param",
"text": "data"
}
]
}
],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-app-theme/app-theme.tsx",
"encapsulation": "none",
"tag": "n-app-theme",
"readme": "# N-APP-THEME\n\nThe `<n-app-theme>` element checks for the preferred light/dark theme preference of the\nuser and sets the interface state: theme, accordingly.\n\n",
"docs": "This element checks for the preferred light/dark theme preference of the\nuser and sets the ui state: theme, accordingly.",
"docsTags": [
{
"name": "system",
"text": "app"
}
],
"usage": {
"basic": "\nAdd this tag somewhere close to the top of the application to auto-adjust the theme class\nbased on the user's preferences.\n\nUse it in conjunction with the [`n-app-theme-switch`](/components/n-app-theme-switch) element\nto give users control of which theme should be applied.\n\n```html\n<n-app>\n <n-app-theme> \n </n-app-theme>\n</n-app>\n```",
"custom-class": "\nTo set a custom class name:\n\n```html\n<n-app>\n <n-app-theme \n dark-class='midnight'>\n </n-app-theme>\n</n-app>\n```"
},
"props": [
{
"name": "darkClass",
"type": "string",
"mutable": false,
"attr": "dark-class",
"reflectToAttr": false,
"docs": "Change the class name that is added to the\ntarget element when the theme is determined to\nbe dark.",
"docsTags": [],
"default": "'dark'",
"values": [
{
"type": "string"
}
],
"optional": false,
"required": false
},
{
"name": "display",
"type": "boolean",
"mutable": false,
"attr": "display",
"reflectToAttr": false,
"docs": "Display the user's system preference.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "switch",
"type": "boolean",
"mutable": false,
"attr": "switch",
"reflectToAttr": false,
"docs": "This element displays the current theme,\nunless in switch-mode, it will show the opposite.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "targetElement",
"type": "string",
"mutable": false,
"attr": "target-element",
"reflectToAttr": false,
"docs": "Change the element that is decorated with\nthe dark-mode class",
"docsTags": [],
"default": "'body'",
"values": [
{
"type": "string"
}
],
"optional": false,
"required": false
}
],
"methods": [],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-app-theme-switch/app-theme-switch.tsx",
"encapsulation": "none",
"tag": "n-app-theme-switch",
"readme": "# N-APP-THEME-SWITCH\n\nThe `<n-app-theme-switch>` element displays a checkbox to control the dark-theme setting applied to the interface.\n\nDefault: user-preference\n",
"docs": "This element displays a checkbox to control the\ndark-theme setting applied to the ui.\n\nDefault: user-preference",
"docsTags": [
{
"name": "system",
"text": "app"
}
],
"usage": {
"basic": "Add the `<n-app-theme-switch>` element to any page to allow the user to adjust the setting. You can style it using standard CSS and if necessary, add CSS styles directly to the input element using the **classes** attribute."
},
"props": [
{
"name": "inputClass",
"type": "string | undefined",
"mutable": false,
"attr": "input-class",
"reflectToAttr": false,
"docs": "The class to add to the inner input.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "inputId",
"type": "string | undefined",
"mutable": false,
"attr": "input-id",
"reflectToAttr": false,
"docs": "The inner input ID",
"docsTags": [],
"default": "'dark-mode'",
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
}
],
"methods": [],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-audio/audio.tsx",
"encapsulation": "shadow",
"tag": "n-audio",
"readme": "# N-AUDIO\n\nThis element is responsible for playing audio requested via the [action](/actions) bus. Internally it holds two players, one for music and another for sounds.\n\nThe audio-tracks are declaratively defined in HTML to respond to user interactions. Unlike a typical playlist, the audio items are configured with behavior rules that help orchestrate overlapping sound and music sound.\n\nWhile it can be placed anywhere, only ONE player is allowed within an HTML document. Loading a second element will have no effect.\n\nOnce in-place, the [`n-audio`](/components/n-audio) element listens on the **audio** topic for commands.\n\n> ℹ️ Note: This element subscribes to route-change notifications - as some audio clips are meant to end when the route changes.\n\n## Audio Actions\n\nTo operate the player, it is easiest to just use the `<n-audio-load-*>` elements to pre-load the audio. Then declare the actions using the [`n-action-activator`](/components/n-action-activator) element.\n\n```html\n<n-view-prompt>\n <n-audio-action-sound-load \n track-id='<unique-id>' \n src='<url>'>\n </n-audio-action-sound-load>\n <n-action-activator ...>\n <n-audio-action-sound\n command='<command>'\n track-id='<id>'\n value='<value>'\n ></n-audio-action-sound>\n </n-action-activator>\n</n-view-prompt>\n```\n\n## Display\n\nThis player can be configured to display or remain hidden. When displayed, it shows a single icon when a file is loaded and a different icon when it is playing. Clicking it should toggle pause for both of the players simultaneously.\n\n\n```html\n<n-audio display> </n-audio>\n```\n\n### Looping\n\nOnly the music player will support looping. Default is true. Looping audio loops until its discard event occurs.\n\nIf audio is set to loop with no deactivation, any new configuration will end it. For instance, if new audio is configured to activate in a queued fashion, the looping audio should stop, allowing the queued audio to play when it ends.\n\n### Discard Strategy\n\nEach audio track-request defines when it should be stopped and removed from the queue. This allows for music to plays between routes. By default, a route-change will empty the queue of any unplayed audio.\n\n- **route**: When the route changes (default for unmarked)\n- **next**: Play/queue until route or another audio is queued.\n- **none**: Play until a new track is played (default for music)\n\n### Volume Easing\n\nHard discards or play ease out the audio with a .5 second fade-out before playing the next clip.\n",
"docs": "Use this element only once per page to enable audio features.\nIt will add a CDN reference to Howler.js:\n<https://cdn.jsdelivr.net/npm/howler@2.2.3/dist/howler.core.min.js>",
"docsTags": [
{
"name": "system",
"text": "audio"
},
{
"name": "extension",
"text": "actions"
},
{
"name": "extension",
"text": "provider"
}
],
"usage": {
"basic": "## Display\n\nThis player can be configured to display or remain hidden. When displayed, it shows a single icon when a file is loaded and a different icon when it is playing. Clicking it should toggle pause for both of the players simultaneously.\n\n\n```html\n<n-audio display> </n-audio>\n```"
},
"props": [
{
"name": "actions",
"type": "AudioActionListener | undefined",
"mutable": true,
"reflectToAttr": false,
"docs": "A reference to the action listener for testing.",
"docsTags": [],
"values": [
{
"type": "AudioActionListener"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "dataProvider",
"type": "boolean",
"mutable": false,
"attr": "data-provider",
"reflectToAttr": false,
"docs": "Experimental support for providing audio-data in the\ndata-provider system.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "debug",
"type": "boolean",
"mutable": false,
"attr": "debug",
"reflectToAttr": false,
"docs": "Use debug for verbose logging. Useful for figuring\nthings out.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "display",
"type": "boolean",
"mutable": false,
"attr": "display",
"reflectToAttr": false,
"docs": "The display mode enabled shows player state and stats.\nNo track information or duration is to be displayed.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "howlerVersion",
"type": "string",
"mutable": false,
"attr": "howler-version",
"reflectToAttr": false,
"docs": "The Howler.js Script Reference",
"docsTags": [],
"default": "'2.2.3'",
"values": [
{
"type": "string"
}
],
"optional": false,
"required": false
}
],
"methods": [],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [
"n-content-reference"
],
"dependencyGraph": {
"n-audio": [
"n-content-reference"
]
}
},
{
"filePath": "./src/components/n-audio-action-music/audio-action-music.tsx",
"encapsulation": "shadow",
"tag": "n-audio-action-music",
"readme": "# N-AUDIO-ACTION-MUSIC\n\nThis element represents an action to be fired. This specialized action encapsulates the required parameters needed for audio-based actions, for music.\n\n> ℹ️ Note: See the [audio](/audio) systems documentation for more information.\n",
"docs": "This element represents an action to be fired. This\nspecialized action encapsulates required parameters\nneeded for audio-based actions, for music.",
"docsTags": [
{
"name": "system",
"text": "audio"
},
{
"name": "system",
"text": "actions"
}
],
"usage": {
"basic": ""
},
"props": [
{
"name": "command",
"type": "\"mute\" | \"pause\" | \"resume\" | \"seek\" | \"start\" | \"volume\"",
"mutable": false,
"attr": "command",
"reflectToAttr": false,
"docs": "The command to execute.",
"docsTags": [],
"values": [
{
"value": "mute",
"type": "string"
},
{
"value": "pause",
"type": "string"
},
{
"value": "resume",
"type": "string"
},
{
"value": "seek",
"type": "string"
},
{
"value": "start",
"type": "string"
},
{
"value": "volume",
"type": "string"
}
],
"optional": false,
"required": true
},
{
"name": "topic",
"type": "\"audio\"",
"mutable": false,
"attr": "topic",
"reflectToAttr": false,
"docs": "Readonly topic",
"docsTags": [],
"default": "AUDIO_TOPIC",
"values": [
{
"value": "audio",
"type": "string"
}
],
"optional": false,
"required": false
},
{
"name": "trackId",
"type": "string | undefined",
"mutable": false,
"attr": "track-id",
"reflectToAttr": false,
"docs": "The track to target.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "value",
"type": "boolean | number | string | undefined",
"mutable": false,
"attr": "value",
"reflectToAttr": false,
"docs": "The value payload for the command.",
"docsTags": [],
"values": [
{
"type": "boolean"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
},
{
"name": "when",
"type": "string | undefined",
"mutable": false,
"attr": "when",
"reflectToAttr": false,
"docs": "A predicate to evaluate prior to sending the action.",
"docsTags": [],
"values": [
{
"type": "string"
},
{
"type": "undefined"
}
],
"optional": true,
"required": false
}
],
"methods": [
{
"name": "getAction",
"returns": {
"type": "Promise<EventAction<any> | null>",
"docs": ""
},
"signature": "getAction() => Promise<EventAction<any> | null>",
"parameters": [],
"docs": "Get the underlying actionEvent instance. Used by the n-action-activator element.",
"docsTags": []
},
{
"name": "sendAction",
"returns": {
"type": "Promise<void>",
"docs": ""
},
"signature": "sendAction(data?: Record<string, any> | undefined) => Promise<void>",
"parameters": [],
"docs": "Send this action to the the action messaging system.",
"docsTags": []
}
],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-audio-action-music-load/audio-action-music-load.tsx",
"encapsulation": "shadow",
"tag": "n-audio-action-music-load",
"readme": "# N-AUDIO-ACTION-MUSIC-LOAD\n\nThis component declares audio playback. The [`n-audio-action-music-load`](/components/n-audio-action-music-load) element represents audio files and play behaviors. They are sent to the audio player to pre-load or play when the route is active. The player manages them according to their settings.\n\n> ℹ️ Note: See the [audio](/audio) systems documentation for more information.\n\n## Usage\n\n```html\n<n-view-prompt>\n <n-audio-action-music-load\n mode='play|load'\n track-id='<unique-id>'\n src='<url>'\n discard='route|video|next|none'\n loop\n track\n ></n-audio-action-music-load>\n</n-view-prompt>\n```\n\n### Simple\n\n```html\n<n-view-prompt>\n <n-audio-action-music-load \n track-id='<unique-id>' \n src='<url>'>\n </n-audio-action-music-load>\n</n-view-prompt>\n```\n\n```html\n<n-view-prompt>\n <n-audio-action-music-load\n mode='queue' \n id='<unique-id>' \n src='<url>' \n discard='none' \n loop>\n </n-audio-action-music-load>\n</n-view-prompt>\n```\n\n#### Mode\n\n- **queue**: (default) plays after the previous audio is complete or when it's requested.\n- **play**: stop any playing audio and play now, buffering be-damned.\n- **wait**: wait for action before playing, any currently playing audio continues.\n\n#### Discard\n\n- **video**: when any video plays (default for sound)\n- **state**: state changes\n- **event**: wait for a stop event (or any other activation)\n- **none**: loop until stopped or updated by new state (default for music)\n\n#### Track\n\nIf audio has replay set to true, re-entry to the originating state will re-activate the audio if the previous audio has been deactivated. The default is false.\n",
"docs": "This element declares audio used within this \\<n-view-prompt\\> route.\nThe \\<n-audio-action-sound-load\\> instructs the player to load audio files\nwhile defining play behaviors.\n\nThe audio player will pre-load or play when the route is active.\nThe player manages them according to their settings.",
"docsTags": [
{
"name": "system",
"text": "audio"
},
{
"name": "system",
"text": "actions"
}
],
"usage": {
"basic": ""
},
"props": [
{
"name": "deferLoad",
"type": "boolean",
"mutable": true,
"attr": "defer-load",
"reflectToAttr": false,
"docs": "If set, disables auto-rendering of this instance.\nTo fetch the contents change to false or remove\nattribute.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "discard",
"type": "\"next\" | \"none\" | \"route\"",
"mutable": false,
"attr": "discard",
"reflectToAttr": false,
"docs": "The discard strategy the player should use for this file.",
"docsTags": [],
"default": "'route'",
"values": [
{
"value": "next",
"type": "string"
},
{
"value": "none",
"type": "string"
},
{
"value": "route",
"type": "string"
}
],
"optional": false,
"required": false
},
{
"name": "loop",
"type": "boolean",
"mutable": false,
"attr": "loop",
"reflectToAttr": false,
"docs": "Set this to true to have the audio file loop.",
"docsTags": [],
"default": "false",
"values": [
{
"type": "boolean"
}
],
"optional": false,
"required": false
},
{
"name": "mode",
"type": "\"load\" | \"play\" | \"queue\"",
"mutable": false,
"attr": "mode",
"reflectToAttr": false,
"docs": "This is the loading strategy that determines\nwhat it should do after the file is retrieved.",
"docsTags": [],
"default": "'queue'",
"values": [
{
"value": "load",
"type": "string"
},
{
"value": "play",
"type": "string"
},
{
"value": "queue",
"type": "string"
}
],
"optional": false,
"required": false
},
{
"name": "src",
"type": "string",
"mutable": false,
"attr": "src",
"reflectToAttr": false,
"docs": "The path to the audio-file.",
"docsTags": [
{
"name": "required"
}
],
"values": [
{
"type": "string"
}
],
"optional": false,
"required": true
},
{
"name": "trackId",
"type": "string",
"mutable": false,
"attr": "track-id",
"reflectToAttr": false,
"docs": "The identifier for this music track",
"docsTags": [],
"values": [
{
"type": "string"
}
],
"optional": false,
"required": true
}
],
"methods": [
{
"name": "getAction",
"returns": {
"type": "Promise<EventAction<any>>",
"docs": ""
},
"signature": "getAction() => Promise<EventAction<AudioInfo | AudioRequest | any>>",
"parameters": [],
"docs": "Get the underlying actionEvent instance.",
"docsTags": []
},
{
"name": "sendAction",
"returns": {
"type": "Promise<void>",
"docs": ""
},
"signature": "sendAction(data?: Record<string, any> | undefined) => Promise<void>",
"parameters": [],
"docs": "Send this action to the the action messaging system.",
"docsTags": []
}
],
"events": [],
"listeners": [],
"styles": [],
"slots": [],
"parts": [],
"dependents": [],
"dependencies": [],
"dependencyGraph": {}
},
{
"filePath": "./src/components/n-audio-action-sound/audio-action-sound.tsx",
"encapsulation": "shadow",
"tag": "n-audio-action-sound",
"readme": "# N-AUDIO-ACTION-SOUND\n\nThis element represents an action to be fired. This specialized action encapsulates the required parameters needed for audio-based actions, for sound.\n\n> ℹ️ Note: See the [audio](/audio) systems documentation for more information.\n",
"docs": "This element represents an action to be fired. This\nspecialized action encapsulates required parameters\nneeded for audio-based actions, for sound.",
"docsTags": [
{
"name": "system",
"text": "audio"
},
{
"name": "system",
"text": "actions"
}
],
"usage": {
"basic": ""
},
"props": [
{
"name": "command",
"type": "\"mute\" | \"pause\" | \"resume\" | \"seek\" | \"start\" | \"volume\"",
"mutable": false,
"attr": "command",
"reflectToAttr": false,
"docs": "The command to execute.",
"docsTags": [],
"values": [
{