AuLoader improvements

This tries to match the Webuniversum `<vl-ui-loader>` component as good as possible.

It's now possible to display a visual text, making it more suited for page loading animations without having to create a custom component.

We also support the inline version of the loading  text.

The existing options that weren't supported by the `<vl-ui-loader>` component are now deprecated.

Author: Windvis

addon/components/au-loader.gts

@@ -1,31 +1,94 @@
 import Component from '@glimmer/component';
+import { deprecate } from '@ember/debug';
 
 export interface AuLoaderSignature {
   Args: {
+    inline?: boolean;
+    hiddenMessage?: boolean;
+    // Deprecated arguments
     disableMessage?: boolean;
     message?: string;
     padding?: 'small' | 'large';
   };
+  Blocks: {
+    default: [];
+  };
   Element: HTMLDivElement;
 }
 
 export default class AuLoader extends Component<AuLoaderSignature> {
   get padding() {
+    deprecate('[AuLoader] `@padding` is deprecated.', !this.args.padding, {
+      id: '@appuniversum/ember-appuniversum.au-loader-padding',
+      until: '4.0.0',
+      for: '@appuniversum/ember-appuniversum',
+      since: {
+        available: '3.1.0',
+        enabled: '3.1.0',
+      },
+    });
+
     if (this.args.padding == 'small') return 'au-c-loader--small';
     if (this.args.padding == 'large') return 'au-c-loader--large';
     else return '';
   }
 
   get message() {
+    deprecate(
+      '[AuLoader] `@message` is deprecated. Provide it using the default block instead.',
+      !this.args.message,
+      {
+        id: '@appuniversum/ember-appuniversum.au-loader-message',
+        until: '4.0.0',
+        for: '@appuniversum/ember-appuniversum',
+        since: {
+          available: '3.1.0',
+          enabled: '3.1.0',
+        },
+      },
+    );
     return this.args.message || 'Aan het laden';
   }
 
+  get disableMessage() {
+    deprecate(
+      '[AuLoader] `@disableMessage` is deprecated. A message should be provided for accessibility reasons.',
+      !('disableMessage' in this.args),
+      {
+        id: '@appuniversum/ember-appuniversum.au-loader-disableMessage',
+        until: '4.0.0',
+        for: '@appuniversum/ember-appuniversum',
+        since: {
+          available: '3.1.0',
+          enabled: '3.1.0',
+        },
+      },
+    );
+    return this.args.disableMessage;
+  }
+
   <template>
-    <div class="au-c-loader {{this.padding}}" ...attributes>
-      <div class="au-c-loader__animation" aria-hidden="true"></div>
-      {{#unless @disableMessage}}
-        <span class="au-u-hidden-visually">{{this.message}}</span>
-      {{/unless}}
-    </div>
+    {{#if (has-block)}}
+      <div class="au-c-loader au-c-loader--new" ...attributes>
+        <div class="au-c-loader__animation" aria-hidden="true"></div>
+        {{#if @inline}}
+          <span
+            class="au-u-para {{if @hiddenMessage 'au-u-hidden-visually'}}"
+          >{{~yield~}}</span>
+        {{else}}
+          <p
+            class="au-u-para {{if @hiddenMessage 'au-u-hidden-visually'}}"
+          >{{yield}}</p>
+        {{/if}}
+      </div>
+    {{else}}
+      {{!TODO: display a deprecation warning when the user isn't using the block version}}
+      <div class="au-c-loader {{this.padding}}" ...attributes>
+        <div class="au-c-loader__animation" aria-hidden="true"></div>
+        {{#unless this.disableMessage}}
+          <span class="au-u-hidden-visually">{{this.message}}</span>
+        {{/unless}}
+      </div>
+    {{/if}}
   </template>
 }

stories/5-components/Notifications/AuLoader.stories.js

@@ -3,16 +3,15 @@ import { hbs } from 'ember-cli-htmlbars';
 export default {
   title: 'Components/Notifications/AuLoader',
   argTypes: {
-    padding: {
-      control: 'select',
-      options: ['default', 'small', 'large'],
-      description: 'Set the padding of the loader',
-    },
     message: {
       control: 'text',
-      description: 'Set the hidden loading text',
+      description: 'Set the loading text',
+    },
+    inline: {
+      control: 'boolean',
+      description: 'Use the inline version of the loader',
     },
-    disableMessage: {
+    hiddenMessage: {
       control: 'boolean',
       description: 'Remove the loading text',
     },
@@ -24,13 +23,16 @@ export default {
 
 const Template = (args) => ({
   template: hbs`
-    <AuLoader @padding={{this.padding}} @message={{this.message}} @disableMessage={{this.disableMessage}} />`,
+    <AuLoader
+      @inline={{this.inline}}
+      @hiddenMessage={{this.hiddenMessage}}
+    >{{this.message}}</AuLoader>`,
   context: args,
 });
 
 export const Component = Template.bind({});
 Component.args = {
-  padding: 'default',
   message: 'Aan het laden',
-  disableMessage: false,
+  inline: false,
+  hiddenMessage: false,
 };

styles/components/_c-loader.scss

@@ -9,6 +9,17 @@
   display: block;
 }
 
+// Overrides for the default loader, to keep backwards compatibility.
+// merge these with the base styles when we drop support for the previous implementation.
+.au-c-loader--new {
+  text-align: center;
+  .au-c-loader__animation {
+    display: inline-block;
+    width: 3rem;
+    height: 1.8rem;
+  }
+}
+
 .au-c-loader__animation {
   display: block;
   position: relative;

tests/dummy/app/templates/application.hbs

@@ -0,0 +1,3 @@
+<AuLoader>Pagina is aan het laden</AuLoader>
+<AuLoader @inline={{true}}>Pagina is aan het laden</AuLoader>
+<AuLoader />

tests/helpers/deprecations.js tests/helpers/deprecations.ts

@@ -1,12 +1,14 @@
 import { getDeprecations } from '@ember/test-helpers';
 
-export function hasDeprecation(deprecationMessage) {
+export function hasDeprecation(deprecationMessage: string): boolean {
   return getDeprecations().some(
     (deprecation) => deprecation.message === deprecationMessage,
   );
 }
 
-export function hasDeprecationStartingWith(deprecationMessage) {
+export function hasDeprecationStartingWith(
+  deprecationMessage: string,
+): boolean {
   return getDeprecations().some((deprecation) =>
     deprecation.message.startsWith(deprecationMessage),
   );

tests/integration/components/au-loader-test.gts

@@ -1,11 +1,43 @@
-import { module, test } from 'qunit';
-import { setupRenderingTest } from 'ember-qunit';
-import { render } from '@ember/test-helpers';
 import AuLoader from '@appuniversum/ember-appuniversum/components/au-loader';
+import { getRootElement, render } from '@ember/test-helpers';
+import { queryByText } from '@testing-library/dom';
+import { hasDeprecationStartingWith } from 'dummy/tests/helpers/deprecations';
+import { setupRenderingTest } from 'ember-qunit';
+import { module, test } from 'qunit';
 
 module('Integration | Component | au-loader', function (hooks) {
   setupRenderingTest(hooks);
 
+  test('it uses the block contents as the loading message', async function (assert) {
+    await render(
+      <template>
+        <AuLoader>
+          Pagina is aan het laden
+        </AuLoader>
+      </template>,
+    );
+
+    assert.dom().hasText('Pagina is aan het laden');
+  });
+
+  test('it supports visually hiding the loading text', async function (assert) {
+    await render(
+      <template>
+        <AuLoader @hiddenMessage={{true}}>
+          Pagina is aan het laden
+        </AuLoader>
+      </template>,
+    );
+
+    const root = getRootElement() as HTMLElement;
+    const text = queryByText(root, 'Pagina is aan het laden') as HTMLElement;
+
+    // Hacky way to test if the text is visible.
+    // `assert.dom(text).isNotVisible()` doesn't work here because of the styles we use for the au-u-hidden-visually class.
+    assert.true(text.offsetHeight <= 1);
+    assert.true(text.offsetWidth <= 1);
+  });
+
   test('it renders a hidden loading text for screen readers', async function (assert) {
     await render(<template><AuLoader /></template>);
 
@@ -16,11 +48,25 @@ module('Integration | Component | au-loader', function (hooks) {
     await render(<template><AuLoader @message="Loading" /></template>);
 
     assert.dom().hasText('Loading');
+    assert.true(
+      hasDeprecationStartingWith('[AuLoader] `@message` is deprecated.'),
+    );
   });
 
   test('it supports disabling the hidden message', async function (assert) {
     await render(<template><AuLoader @disableMessage={{true}} /></template>);
 
     assert.dom().hasNoText();
+    assert.true(
+      hasDeprecationStartingWith('[AuLoader] `@disableMessage` is deprecated.'),
+    );
+  });
+
+  test('@padding shows a deprecation', async function (assert) {
+    await render(<template><AuLoader @padding="small" /></template>);
+
+    assert.true(
+      hasDeprecationStartingWith('[AuLoader] `@padding` is deprecated.'),
+    );
   });
 });