@angular-wave/angular.ts 0.7.2 → 0.7.4

package/docs/content/docs/provider/logProvider.md

@@ -0,0 +1,59 @@
+---
+title: $logProvider
+description: >
+  Configuration provider for `$log` service.
+---
+
+### Description
+
+Instance of [LogProvider](../../../typedoc/classes/LogProvider.html) for
+configuring how the application logs messages.
+
+### Properties
+
+---
+
+#### $logProvider.debug
+
+Enable or disable debug-level logging. Also see
+[debug property](../../../typedoc/classes/LogProvider.html#debug).
+
+- **Type:** boolean
+- **Default:** `false`
+- **Example:**
+
+  ```js
+  angular.module('demo', []).config(($logProvider) => {
+    $logProvider.debug = true;
+  });
+  ```
+
+### Methods
+
+---
+
+#### $logProvider.setLogger()
+
+Override the default logger with a custom implementation of the
+[LogService](../../../typedoc/interfaces/LogService.html) interface.
+
+- **Parameter:**
+  [LogServiceFactory](../../../typedoc/types/LogServiceFactory.html)
+
+- **Example:**
+
+  ```js
+  angular.module('demo', []).config(($logProvider) => {
+    $logProvider.setLogger(() => ({
+      log: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+      debug: () => {},
+    }));
+  });
+  ```
+
+---
+
+For service description, see [$log](../../../docs/service/log).

package/docs/content/docs/provider/templateCacheProvider.md

@@ -0,0 +1,35 @@
+---
+title: $templateCacheProvider
+description: >
+  Cache provider for `$templateCache` service.
+---
+
+### Description
+
+Initializes cache instancce for `$templateCache` service as an empty
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
+object.
+
+### Properties
+
+---
+
+#### $templateCacheProvider.cache
+
+Customize cache instance.
+
+- **Type:** [TemplateCache](../../../typedoc/types/TemplateCache.html)
+- **Default:** `Map`
+
+- **Example:**
+
+  ```js
+  angular.module('demo', []).config(($templateCacheProvider) => {
+    templateCacheProvider.cache.set('test.html', 'hello');
+  });
+  ```
+
+---
+
+For service description, see
+[$templateCache](../../../docs/service/templatecache).

package/docs/content/docs/service/_index.md

@@ -0,0 +1,4 @@
+---
+title: Services
+weight: 40
+---

package/docs/content/docs/service/eventBus.md

@@ -0,0 +1,56 @@
+---
+title: $eventBus
+description: >
+  Pubsub messaging service
+---
+
+### Description
+
+A messaging service, backed by an instance of
+[PubSub](../../../typedoc/classes/PubSub.html). This implementation is based on
+the original
+[Google Closure PubSub](https://google.github.io/closure-library/api/goog.pubsub.PubSub.html)
+but uses
+[`Promise.resolve()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve)
+instead of
+[`Window.setTimeout()`](https://developer.mozilla.org/en-US/docs/Web/API/Window/setTimeout)
+for its async implementation. `$eventBus` allows communication between an
+Angular application instance and the outside context, which can be a different
+module, a non-Angular application, a third-party party library, or even a WASM
+application. Additionally, `$eventBus` can be used to communicate directly with
+a template, using [`ng-channel`](../../../docs/directive/channel) directive.
+
+`$eventBus` should not be used for communicating between Angular's own
+primitives.
+
+- **For sharing application state**: use custom Services and Factories that
+  encapsulate your business logic and manage your model.
+- **For intercomponent communication**: use `$scope.$on()`, `$scope.$emit()`,
+  and `$scope.$broadcast()` methods.
+
+The example below demonstrates communication between the global `window` context
+and a controller. **Note**: Ensure topic clean-up after the `$scope` is
+destroyed
+
+#### Example
+
+{{< showhtml src="examples/eventbus/eventbus.html" >}}
+
+{{< showjs src="examples/eventbus/eventbus.js" >}}
+
+---
+
+#### Demo
+
+{{< showraw src="examples/eventbus/eventbus.html" >}}
+
+<script>
+{{< showraw src="examples/eventbus/eventbus.js" >}}
+</script>
+
+---
+
+For detailed method description, see
+[PubSub](../../../typedoc/classes/PubSub.html)
+
+---

package/docs/content/docs/service/log.md

@@ -0,0 +1,113 @@
+---
+title: $log
+description: >
+  A simple service for logging
+---
+
+### Using `$log`
+
+Default implementation of
+[LogService](../../../typedoc/interfaces/LogService.html) safely writes the
+message into the browser's
+[console](https://developer.mozilla.org/en-US/docs/Web/API/console) (if
+present). The main purpose of this service is to simplify debugging and
+troubleshooting, while allowing the developer to modify the defaults for live
+environments.
+
+##### **Example\***
+
+```js
+angular.module('demo').controller('MyController', ($log) => {
+  $log.log('log');
+  $log.info('info');
+  $log.warn('warn!');
+  $log.error('error');
+  $log.debug('debug');
+});
+```
+
+To reveal the location of the calls to `$log` in the JavaScript console, you can
+"blackbox" the AngularTS source in your browser:
+
+- [Mozilla description of blackboxing](https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Black_box_a_source).
+- [Chrome description of blackboxing](https://developer.chrome.com/devtools/docs/blackboxing).
+
+> Note: Not all browsers support blackboxing.  
+> The default is to log `debug` messages. You can use
+> [`$logProvider.debug`](../../../docs/provider/logprovider/#logprovidersetlogger)
+> to change this.
+
+For configuration and custom implementations, see
+[$logProvider](../../../docs/provider/logprovider).
+
+### Decorating `$log`
+
+You can also optionally override any of the `$log` service methods with
+`$provide` decorator. Below is a simple example that overrides default
+`$log.error` to log errors to both console and a backend endpoint.
+
+##### **Example\***
+
+```js
+angular.module('demo').config(($provide) => {
+  $provide.decorator('$log', ($delegate, $http, $exceptionHandler) => {
+    const originalError = $delegate.error;
+    $delegate.error = () => {
+      originalError.apply($delegate, arguments);
+      const errorMessage = Array.prototype.slice.call(arguments).join(' ');
+      $http.post('/api/log/error', { message: errorMessage });
+    };
+    return $delegate;
+  });
+});
+```
+
+### Overriding `console`
+
+If your application is already heavily reliant on default
+[console](https://developer.mozilla.org/en-US/docs/Web/API/console) logging or
+you are using a third-party library where logging cannot be overriden, you can
+still take advantage of Angular's services by modifying the globals at runtime.
+Below is an example that overrides default `console.error` to logs errors to
+both console and a backend endpoint.
+
+##### **Example\***
+
+```js
+angular.module('demo').run(($http) => {
+  /**
+   * Decorate console.error to log error messages to the server.
+   */
+  const $delegate = window.console.error;
+  window.console.error = (...args) => {
+    try {
+      const errorMessage = args
+        .map((arg) => (arg instanceof Error ? arg.stack : JSON.stringify(arg)))
+        .join(' ');
+      $delegate.apply(console, args);
+      $http.post('/api/log/error', { message: errorMessage });
+    } catch (e) {
+      console.warn(e);
+    }
+  };
+
+  /**
+   * Detect errors thrown outside Angular and report them to the server.
+   */
+  window.addEventListener('error', (e) => {
+    window.console.error(e.error || e.message, e);
+  });
+
+  /**
+   * Optionally: Capture unhandled promise rejections
+   */
+  window.addEventListener('unhandledrejection', (e) => {
+    window.console.error(e.reason || e);
+  });
+});
+```
+
+Combining both `$log` decoration and `console.log` overriding provides a robust
+and flexible error reporting strategy that can adapt to your use-case.
+
+\* array notation and HTTP error handling omitted for brevity

package/docs/content/docs/service/templateCache.md

@@ -0,0 +1,64 @@
+---
+title: $templateCache
+description: >
+  Map object for storing templates
+---
+
+`$templateCache` is a
+[Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map)
+object created by `$templateCacheProvider`.
+
+The first time a template is used, it is loaded in the template cache for quick
+retrieval. You can load templates directly into the cache in a script tag, by
+using $templateRequest, or by consuming the $templateCache service directly.
+
+Adding via the script tag:
+
+#### Example
+
+```html
+<script type="text/ng-template" id="templateId.html">
+  <p>This is the content of the template</p>
+</script>
+```
+
+Note: the script tag containing the template does not need to be included in the
+head of the document, but it must be a descendent of the $rootElement (e.g.
+element with `ng-app` attribute), otherwise the template will be ignored.
+
+Adding via the `$templateCache` service:
+
+#### Example
+
+```js
+const myApp = angular.module('myApp', []).run(($templateCache) => {
+  $templateCache.set('templateId.html', 'This is the content of the template');
+});
+```
+
+To retrieve the template, simply use it in your component:
+
+```js
+myApp.component('myComponent', {
+  templateUrl: 'templateId.html',
+});
+```
+
+or include it with `ng-include`:
+
+```html
+<div ng-include="'templateId.html`"></div>
+```
+
+or get it via the `$templateCache` service:
+
+```js
+myApp.controller(
+  'Test',
+  class {
+    constructor($templateCache) {
+      const tmp = $templateCache.get('templateId.html');
+    }
+  },
+);
+```

package/docs/docker-compose.yaml

@@ -1,13 +1,12 @@
-version: "3.8"
+version: '3.8'
 
 services:
-
   site:
     image: docsy/docsy-example
     build:
       context: .
     command: server
     ports:
-      - "1313:1313"
+      - '1313:1313'
     volumes:
       - .:/src

package/docs/hugo.yaml

@@ -3,13 +3,6 @@ title: AngularTS
 
 # cSpell:ignore goldmark github hugo readingtime docsy subdir lastmod pygments linenos catmullrom norsk gu
 
-# Language settings
-contentDir: content/en
-defaultContentLanguage: en
-defaultContentLanguageInSubdir: false
-# Useful when translating.
-enableMissingTranslationPlaceholders: true
-
 enableRobotsTXT: true
 
 # Will give values to .Lastmod etc.
@@ -40,15 +33,7 @@ permalinks:
 imaging:
   resampleFilter: CatmullRom
   quality: 75
-  anchor: smart
-
-# Language configuration
-languages:
-  en:
-    languageName: English
-    title: AngularTS
-    params:
-      description: AngularTS documentation site
+  anchor: Smart
 
 markup:
   goldmark:
@@ -129,6 +114,9 @@ params:
   #   authors: Docsy Authors | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0) |
   #   from_year: 2018
 
+  customCSS:
+    - 'css/index.css'
+
   # User interface configuration
   ui:
     # Set to true to disable breadcrumb navigation.
@@ -136,11 +124,12 @@ params:
     # Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
     navbar_logo: true
     # Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
-    navbar_translucent_over_cover_disable: false
+    navbar_translucent_over_cover_disable: true
     # Enable to show the side bar menu in its compact state.
     sidebar_menu_compact: false
     # Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
     sidebar_search_disable: false
+    navbar_menu: true
 
     # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
     # This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
@@ -150,9 +139,13 @@ params:
       enable: true
       # The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
       'yes': >-
-        Glad to hear it! Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.
+        Glad to hear it! Please <a
+        href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we
+        can improve</a>.
       'no': >-
-        Sorry to hear that. Please <a href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we can improve</a>.
+        Sorry to hear that. Please <a
+        href="https://github.com/USERNAME/REPOSITORY/issues/new">tell us how we
+        can improve</a>.
 
     # Adds a reading time to the top of each doc.
     # If you want this feature, but occasionally need to remove the Reading time from a single page,
@@ -199,3 +192,9 @@ module:
   imports:
     - path: github.com/google/docsy
       disable: false
+
+menu:
+  main:
+    - name: 'API'
+      url: '/typedoc/index.html'
+      weight: 50

package/docs/layouts/404.html

@@ -1,7 +1,13 @@
 {{ define "main" -}}
 <div class="td-content">
   <h1>Not found</h1>
-  <p>Oops! This page doesn't exist. Try going back to the <a href="{{ "" | relURL }}">home page</a>.</p>
-  <p>You can learn how to make a 404 page like this in <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.</p>
+  <p>
+    Oops! This page doesn't exist. Try going back to the
+    <a href='{{ "" | relURL }}'>home page</a>.
+  </p>
+  <p>
+    You can learn how to make a 404 page like this in
+    <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.
+  </p>
 </div>
 {{- end }}

package/docs/layouts/partials/hooks/head-end.html

@@ -0,0 +1,3 @@
+<script src="
+    https://cdn.jsdelivr.net/npm/@angular-wave/angular.ts/dist/angular-ts.umd.min.js
+"></script>

package/docs/layouts/shortcodes/showhtml.html

@@ -0,0 +1,2 @@
+{{ $code := readFile (printf "static/%s" (.Get "src")) }} {{ highlight $code
+"html" "" }}

package/docs/layouts/shortcodes/showjs.html

@@ -0,0 +1,2 @@
+{{ $code := readFile (printf "static/%s" (.Get "src")) }} {{ highlight $code
+"js" "" }}

package/docs/layouts/shortcodes/showraw.html

@@ -0,0 +1 @@
+{{ $code := readFile (printf "static/%s" (.Get "src")) }} {{ $code | safeHTML }}

package/docs/static/examples/counter/counter-test.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>AngularTS Test Runner</title>
+
+    <link rel="shortcut icon" type="image/png" href="/images/favicon.ico" />
+    <script src="
+        https://cdn.jsdelivr.net/npm/@angular-wave/angular.ts/dist/angular-ts.umd.min.js
+    "></script>
+  </head>
+  <body>
+    <div ng-app>
+      <div ng-include="'./counter.html'"></div>
+    </div>
+  </body>
+</html>

package/docs/static/examples/counter/counter.html

@@ -0,0 +1,5 @@
+<section ng-app ng-cloak>
+  <button class="btn btn-dark" ng-init="count = 0" ng-click="count = count + 1">
+    Count is: {{ count }}
+  </button>
+</section>

package/docs/static/examples/counter/counter.test.js

@@ -0,0 +1,28 @@
+import { test, expect } from '@playwright/test';
+
+const TEST_URL = 'docs/static/examples/counter/counter-test.html';
+
+test('counter example', async ({ page }) => {
+  await page.goto(TEST_URL);
+  await page.content();
+
+  // Locate the button
+  const counterButton = page.locator('button');
+
+  // Verify initial count
+  await expect(counterButton).toHaveText('Count is: 0');
+
+  // Click once
+  await counterButton.click();
+  await expect(counterButton).toHaveText('Count is: 1');
+
+  // Click again
+  await counterButton.click();
+  await expect(counterButton).toHaveText('Count is: 2');
+
+  // Click three more times
+  await counterButton.click();
+  await counterButton.click();
+  await counterButton.click();
+  await expect(counterButton).toHaveText('Count is: 5');
+});

package/docs/static/examples/eventbus/eventbus-test.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>AngularTS Test Runner</title>
+
+    <link rel="shortcut icon" type="image/png" href="/images/favicon.ico" />
+    <script src="
+        https://cdn.jsdelivr.net/npm/@angular-wave/angular.ts/dist/angular-ts.umd.min.js
+    "></script>
+  </head>
+  <body>
+    <div ng-app="demo">
+      <div ng-include="'./eventbus.html'"></div>
+    </div>
+
+    <script src="./eventbus.js"></script>
+  </body>
+</html>

package/docs/static/examples/eventbus/eventbus.html

@@ -0,0 +1,13 @@
+<section ng-app="demo">
+  <div ng-controller="DemoCtrl as $ctrl">
+    Milliseconds elapsed since the epoch <b>{{ $ctrl.ms }}</b>
+  </div>
+</section>
+
+<!--We are using a regular onclick and `angular` global -->
+<button
+  class="btn btn-dark"
+  onclick="angular.$eventBus.publish('demo', Date.now())"
+>
+  Publish time
+</button>

package/docs/static/examples/eventbus/eventbus.js

@@ -0,0 +1,15 @@
+angular.module('demo', []).controller(
+  'DemoCtrl',
+  class {
+    static $inject = ['$eventBus', '$scope'];
+    constructor($eventBus, $scope) {
+      const key = $eventBus.subscribe('demo', (val) => {
+        // `this.ms = val` will not work because `this` is not a proxy
+        //  to trigger change detection, we access controller as a scope property
+        $scope.$ctrl.ms = val;
+      });
+
+      $scope.$on('$destroy', () => $eventBus.unsubscribeByKey(key));
+    }
+  },
+);

package/docs/static/examples/eventbus/eventbus.test.js

@@ -0,0 +1,19 @@
+import { test, expect } from '@playwright/test';
+
+const TEST_URL = 'docs/static/examples/eventbus/eventbus-test.html';
+
+test('eventbus example', async ({ page }) => {
+  await page.goto(TEST_URL);
+  await page.content();
+  // Click the publish button
+  await page.click('button.btn-dark');
+
+  await expect(page.locator('b')).toHaveText(/^\d+$/, { timeout: 1000 });
+
+  const updatedText = await page.locator('b').innerText();
+  const timestamp = Number(updatedText);
+  const now = Date.now();
+
+  expect(timestamp).toBeGreaterThan(now - 5000); // allow 5 seconds slack
+  expect(timestamp).toBeLessThanOrEqual(now);
+});

package/docs/static/examples/ng-channel/ng-channel-test.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>AngularTS Test Runner</title>
+
+    <link rel="shortcut icon" type="image/png" href="/images/favicon.ico" />
+    <script src="
+        https://cdn.jsdelivr.net/npm/@angular-wave/angular.ts/dist/angular-ts.umd.min.js
+    "></script>
+  </head>
+  <body>
+    <div ng-app>
+      <div ng-include="'./ng-channel.html'"></div>
+    </div>
+  </body>
+</html>

package/docs/static/examples/ng-channel/ng-channel.html

@@ -0,0 +1,24 @@
+<div ng-app>
+  <!-- With empty node -->
+  <div ng-channel="epoch"></div>
+
+  <!-- With template -->
+  <div ng-channel="user">Hello {{ user.firstName }} {{ user.lastName }}</div>
+</div>
+
+<button
+  class="btn btn-dark"
+  onclick='angular.$eventBus.publish("epoch", Date.now())'
+>
+  Publish epoch
+</button>
+
+<button
+  class="btn btn-dark"
+  onclick='angular.$eventBus.publish("user", {user: {
+        firstName: "John",
+        lastName: "Smith" 
+    }})'
+>
+  Publish name
+</button>

package/docs/static/examples/ng-channel/ng-channel.test.js

@@ -0,0 +1,31 @@
+import { test, expect } from '@playwright/test';
+
+const TEST_URL = 'docs/static/examples/ng-channel/ng-channel-test.html';
+
+test('updates empty ng-channel element with published epoch', async ({
+  page,
+}) => {
+  await page.goto(TEST_URL);
+  await page.content();
+  const epochDiv = page.locator('[ng-channel="epoch"]');
+  await expect(epochDiv).toHaveText('');
+
+  await page.click('text=Publish epoch');
+
+  // Wait for innerHTML to be updated
+  await expect(epochDiv).not.toHaveText('');
+  await expect(epochDiv).toContainText(/^\d+$/); // Should be a timestamp
+});
+
+test('updates templated ng-channel element with published user data', async ({
+  page,
+}) => {
+  await page.goto(TEST_URL);
+  await page.content();
+  const userDiv = page.locator('[ng-channel="user"]');
+  await expect(userDiv).toHaveText(/Hello\s*/);
+
+  await page.click('text=Publish name');
+
+  await expect(userDiv).toContainText('Hello John Smith');
+});