feat(router-link): add router-link and deprecate anchor (#18620)

ionic-team · Jun 25, 2019 · d4c7b03 · d4c7b03
1 parent 8a88dd2
commit d4c7b03
Show file tree

Hide file tree

Showing 11 changed files with 333 additions and 56 deletions.
diff --git a/core/api.txt b/core/api.txt
@@ -72,11 +72,9 @@ ion-alert-controller,method,getTop,getTop() => Promise<HTMLIonAlertElement | und
 
 ion-anchor,shadow
 ion-anchor,prop,color,string | undefined,undefined,false,false
-ion-anchor,prop,download,string | undefined,undefined,false,false
 ion-anchor,prop,href,string | undefined,undefined,false,false
 ion-anchor,prop,rel,string | undefined,undefined,false,false
 ion-anchor,prop,routerDirection,"back" | "forward" | "root",'forward',false,false
-ion-anchor,prop,target,string | undefined,undefined,false,false
 ion-anchor,css-prop,--background
 ion-anchor,css-prop,--color
 
@@ -927,6 +925,14 @@ ion-router,method,push,push(url: string, direction?: RouterDirection) => Promise
 ion-router,event,ionRouteDidChange,RouterEventDetail,true
 ion-router,event,ionRouteWillChange,RouterEventDetail,true
 
+ion-router-link,shadow
+ion-router-link,prop,color,string | undefined,undefined,false,false
+ion-router-link,prop,href,string | undefined,undefined,false,false
+ion-router-link,prop,rel,string | undefined,undefined,false,false
+ion-router-link,prop,routerDirection,"back" | "forward" | "root",'forward',false,false
+ion-router-link,css-prop,--background
+ion-router-link,css-prop,--color
+
 ion-router-outlet,shadow
 ion-router-outlet,prop,animated,boolean,true,false,false
 ion-router-outlet,prop,animation,((Animation: Animation, baseEl: any, opts?: any) => Promise<Animation>) | undefined,undefined,false,false

diff --git a/core/src/components.d.ts b/core/src/components.d.ts
@@ -244,10 +244,6 @@ export namespace Components {
     */
     'color'?: Color;
     /**
-    * This attribute instructs browsers to download a URL instead of navigating to it, so the user will be prompted to save it as a local file. If the attribute has a value, it is used as the pre-filled file name in the Save prompt (the user can still change the file name if they want).
-    */
-    'download': string | undefined;
-    /**
     * Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
     */
     'href': string | undefined;
@@ -259,10 +255,6 @@ export namespace Components {
     * When using a router, it specifies the transition direction when navigating to another page using `href`.
     */
     'routerDirection': RouterDirection;
-    /**
-    * Specifies where to display the linked URL. Only applies when an `href` is provided. Special keywords: `"_blank"`, `"_self"`, `"_parent"`, `"_top"`.
-    */
-    'target': string | undefined;
   }
   interface IonApp {}
   interface IonAvatar {}
@@ -2007,6 +1999,24 @@ export namespace Components {
     */
     'useHash': boolean;
   }
+  interface IonRouterLink {
+    /**
+    * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
+    */
+    'color'?: Color;
+    /**
+    * Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
+    */
+    'href': string | undefined;
+    /**
+    * Specifies the relationship of the target object to the link object. The value is a space-separated list of [link types](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types).
+    */
+    'rel': string | undefined;
+    /**
+    * When using a router, it specifies the transition direction when navigating to another page using `href`.
+    */
+    'routerDirection': RouterDirection;
+  }
   interface IonRouterOutlet {
     /**
     * If `true`, the router-outlet should animate the transition of components.
@@ -3160,6 +3170,12 @@ declare global {
     new (): HTMLIonRouterElement;
   };
 
+  interface HTMLIonRouterLinkElement extends Components.IonRouterLink, HTMLStencilElement {}
+  var HTMLIonRouterLinkElement: {
+    prototype: HTMLIonRouterLinkElement;
+    new (): HTMLIonRouterLinkElement;
+  };
+
   interface HTMLIonRouterOutletElement extends Components.IonRouterOutlet, HTMLStencilElement {}
   var HTMLIonRouterOutletElement: {
     prototype: HTMLIonRouterOutletElement;
@@ -3387,6 +3403,7 @@ declare global {
     'ion-route': HTMLIonRouteElement;
     'ion-route-redirect': HTMLIonRouteRedirectElement;
     'ion-router': HTMLIonRouterElement;
+    'ion-router-link': HTMLIonRouterLinkElement;
     'ion-router-outlet': HTMLIonRouterOutletElement;
     'ion-row': HTMLIonRowElement;
     'ion-searchbar': HTMLIonSearchbarElement;
@@ -3557,10 +3574,6 @@ declare namespace LocalJSX {
     */
     'color'?: Color;
     /**
-    * This attribute instructs browsers to download a URL instead of navigating to it, so the user will be prompted to save it as a local file. If the attribute has a value, it is used as the pre-filled file name in the Save prompt (the user can still change the file name if they want).
-    */
-    'download'?: string | undefined;
-    /**
     * Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
     */
     'href'?: string | undefined;
@@ -3572,10 +3585,6 @@ declare namespace LocalJSX {
     * When using a router, it specifies the transition direction when navigating to another page using `href`.
     */
     'routerDirection'?: RouterDirection;
-    /**
-    * Specifies where to display the linked URL. Only applies when an `href` is provided. Special keywords: `"_blank"`, `"_self"`, `"_parent"`, `"_top"`.
-    */
-    'target'?: string | undefined;
   }
   interface IonApp extends JSXBase.HTMLAttributes<HTMLIonAppElement> {}
   interface IonAvatar extends JSXBase.HTMLAttributes<HTMLIonAvatarElement> {}
@@ -5218,6 +5227,24 @@ declare namespace LocalJSX {
     */
     'useHash'?: boolean;
   }
+  interface IonRouterLink extends JSXBase.HTMLAttributes<HTMLIonRouterLinkElement> {
+    /**
+    * The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).
+    */
+    'color'?: Color;
+    /**
+    * Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.
+    */
+    'href'?: string | undefined;
+    /**
+    * Specifies the relationship of the target object to the link object. The value is a space-separated list of [link types](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types).
+    */
+    'rel'?: string | undefined;
+    /**
+    * When using a router, it specifies the transition direction when navigating to another page using `href`.
+    */
+    'routerDirection'?: RouterDirection;
+  }
   interface IonRouterOutlet extends JSXBase.HTMLAttributes<HTMLIonRouterOutletElement> {
     /**
     * If `true`, the router-outlet should animate the transition of components.
@@ -6036,6 +6063,7 @@ declare namespace LocalJSX {
     'ion-route': IonRoute;
     'ion-route-redirect': IonRouteRedirect;
     'ion-router': IonRouter;
+    'ion-router-link': IonRouterLink;
     'ion-router-outlet': IonRouterOutlet;
     'ion-row': IonRow;
     'ion-searchbar': IonSearchbar;

diff --git a/core/src/components/anchor/anchor.scss b/core/src/components/anchor/anchor.scss
@@ -5,8 +5,8 @@
 
 :host {
   /**
-   * @prop --background: Background of the badge
-   * @prop --color: Text color of the badge
+   * @prop --background: Background of the anchor
+   * @prop --color: Text color of the anchor
    */
   --background: transparent;
   --color: #{ion-color(primary, base)};

diff --git a/core/src/components/anchor/anchor.tsx b/core/src/components/anchor/anchor.tsx
@@ -2,15 +2,17 @@ import { Component, ComponentInterface, Host, Prop, h } from '@stencil/core';
 
 import { getIonMode } from '../../global/ionic-global';
 import { Color, RouterDirection } from '../../interface';
-import { AnchorInterface } from '../../utils/element-interface';
 import { createColorClasses, openURL } from '../../utils/theme';
 
+/**
+ * @deprecated Use `ion-router-link` instead.
+ */
 @Component({
   tag: 'ion-anchor',
   styleUrl: 'anchor.scss',
   shadow: true
 })
-export class Anchor implements ComponentInterface, AnchorInterface {
+export class Anchor implements ComponentInterface {
 
   /**
    * The color to use from your application's color palette.
@@ -19,14 +21,6 @@ export class Anchor implements ComponentInterface, AnchorInterface {
    */
   @Prop() color?: Color;
 
-  /**
-   * This attribute instructs browsers to download a URL instead of navigating to
-   * it, so the user will be prompted to save it as a local file. If the attribute
-   * has a value, it is used as the pre-filled file name in the Save prompt
-   * (the user can still change the file name if they want).
-   */
-  @Prop() download: string | undefined;
-
   /**
    * Contains a URL or a URL fragment that the hyperlink points to.
    * If this property is set, an anchor tag will be rendered.
@@ -45,12 +39,9 @@ export class Anchor implements ComponentInterface, AnchorInterface {
    */
   @Prop() routerDirection: RouterDirection = 'forward';
 
-  /**
-   * Specifies where to display the linked URL.
-   * Only applies when an `href` is provided.
-   * Special keywords: `"_blank"`, `"_self"`, `"_parent"`, `"_top"`.
-   */
-  @Prop() target: string | undefined;
+  componentDidLoad() {
+    console.warn('The <ion-anchor> component has been deprecated. Please use an <ion-router-link> if you are using a vanilla JS or Stencil project or an <a> with the Angular router.');
+  }
 
   private onClick = (ev: Event) => {
     openURL(this.href, ev, this.routerDirection);
@@ -59,10 +50,8 @@ export class Anchor implements ComponentInterface, AnchorInterface {
   render() {
     const mode = getIonMode(this);
     const attrs = {
-      download: this.download,
       href: this.href,
-      rel: this.rel,
-      target: this.target
+      rel: this.rel
     };
     return (
       <Host

diff --git a/core/src/components/anchor/readme.md b/core/src/components/anchor/readme.md
@@ -1,30 +1,26 @@
 # ion-anchor
 
-The Anchor component is used for navigating to a specified link. Similar to the browser's anchor tag, it can accept a href for the location, and a direction for the transition animation.
-
-> Note: this component should only be used with vanilla and Stencil JavaScript projects. For Angular projects, use an `<a>` and `routerLink` with the Angular router.
+> [DEPRECATED]. Use [ion-router-link](../router-link) instead.
 
 <!-- Auto Generated Below -->
 
 
 ## Properties
 
-| Property          | Attribute          | Description                                                                                                                                                                                                                                                                               | Type                            | Default     |
-| ----------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------- |
-| `color`           | `color`            | The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics).                    | `string \| undefined`           | `undefined` |
-| `download`        | `download`         | This attribute instructs browsers to download a URL instead of navigating to it, so the user will be prompted to save it as a local file. If the attribute has a value, it is used as the pre-filled file name in the Save prompt (the user can still change the file name if they want). | `string \| undefined`           | `undefined` |
-| `href`            | `href`             | Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.                                                                                                                                                                   | `string \| undefined`           | `undefined` |
-| `rel`             | `rel`              | Specifies the relationship of the target object to the link object. The value is a space-separated list of [link types](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types).                                                                                                    | `string \| undefined`           | `undefined` |
-| `routerDirection` | `router-direction` | When using a router, it specifies the transition direction when navigating to another page using `href`.                                                                                                                                                                                  | `"back" \| "forward" \| "root"` | `'forward'` |
-| `target`          | `target`           | Specifies where to display the linked URL. Only applies when an `href` is provided. Special keywords: `"_blank"`, `"_self"`, `"_parent"`, `"_top"`.                                                                                                                                       | `string \| undefined`           | `undefined` |
+| Property          | Attribute          | Description                                                                                                                                                                                                                                                            | Type                            | Default     |
+| ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------- |
+| `color`           | `color`            | The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics). | `string \| undefined`           | `undefined` |
+| `href`            | `href`             | Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.                                                                                                                                                | `string \| undefined`           | `undefined` |
+| `rel`             | `rel`              | Specifies the relationship of the target object to the link object. The value is a space-separated list of [link types](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types).                                                                                 | `string \| undefined`           | `undefined` |
+| `routerDirection` | `router-direction` | When using a router, it specifies the transition direction when navigating to another page using `href`.                                                                                                                                                               | `"back" \| "forward" \| "root"` | `'forward'` |
 
 
 ## CSS Custom Properties
 
-| Name           | Description             |
-| -------------- | ----------------------- |
-| `--background` | Background of the badge |
-| `--color`      | Text color of the badge |
+| Name           | Description              |
+| -------------- | ------------------------ |
+| `--background` | Background of the anchor |
+| `--color`      | Text color of the anchor |
 
 
 ----------------------------------------------

diff --git a/core/src/components/router-link/readme.md b/core/src/components/router-link/readme.md
@@ -0,0 +1,30 @@
+# ion-router-link
+
+The router link component is used for navigating to a specified link. Similar to the browser's anchor tag, it can accept a href for the location, and a direction for the transition animation.
+
+> Note: this component should only be used with vanilla and Stencil JavaScript projects. For Angular projects, use an `<a>` and `routerLink` with the Angular router.
+
+<!-- Auto Generated Below -->
+
+
+## Properties
+
+| Property          | Attribute          | Description                                                                                                                                                                                                                                                            | Type                            | Default     |
+| ----------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ----------- |
+| `color`           | `color`            | The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see [theming](/docs/theming/basics). | `string \| undefined`           | `undefined` |
+| `href`            | `href`             | Contains a URL or a URL fragment that the hyperlink points to. If this property is set, an anchor tag will be rendered.                                                                                                                                                | `string \| undefined`           | `undefined` |
+| `rel`             | `rel`              | Specifies the relationship of the target object to the link object. The value is a space-separated list of [link types](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types).                                                                                 | `string \| undefined`           | `undefined` |
+| `routerDirection` | `router-direction` | When using a router, it specifies the transition direction when navigating to another page using `href`.                                                                                                                                                               | `"back" \| "forward" \| "root"` | `'forward'` |
+
+
+## CSS Custom Properties
+
+| Name           | Description                   |
+| -------------- | ----------------------------- |
+| `--background` | Background of the router link |
+| `--color`      | Text color of the router link |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*
diff --git a/core/src/components/router-link/router-link.scss b/core/src/components/router-link/router-link.scss
@@ -0,0 +1,24 @@
+@import "../../themes/ionic.globals";
+
+// Anchor
+// --------------------------------------------------
+
+:host {
+  /**
+   * @prop --background: Background of the router link
+   * @prop --color: Text color of the router link
+   */
+  --background: transparent;
+  --color: #{ion-color(primary, base)};
+
+  background: var(--background);
+  color: var(--color);
+}
+
+:host(.ion-color) {
+  color: current-color(base);
+}
+
+a {
+  @include text-inherit();
+}