@esri/instant-apps-components

Instant Apps Components

Instant Apps Components, is a library of Web Components (Custom Elements) built with StencilJS, with the purpose of being utilized by ArcGIS Instant Apps. Web Components are browser-compatible elements, use native browser APIs, resuable, and contain encapsulated functionality. Instant Apps Components use Calcite Components, the ArcGIS API for JavaScript, and additional functionality that can be easily implemented into your web map applications. While this library of web components are intended for being used in ArcGIS Instant Apps, these components can be used in any web map application, without being tied to a particular library or framework.

To set up locally, in terminal:

1. git clone https://github.com/Esri/instant-apps-components.git

2. cd packages/instant-apps-components

3. npm install

4. npm start (Wait until build is finished.)

5. Open another terminal and run npm run storybook

Stencil CLI

You can use the stencil CLI to generate the necessary files for your web component.

1. In terminal, run npx stencil generate.

2. Enter the name of your web component with the following naming convention: instant-apps-[YOUR_COMPONENT_NAME].

3. Press Enter/Return.

4. Since this web component library uses sass, you'll need to update your component's stylesheet file extension. i.e. src/components/instant-apps-[YOUR_COMPONENT_NAME]/instant-apps-[YOUR_COMPONENT_NAME].css to src/components/instant-apps-[YOUR_COMPONENT_NAME]/instant-apps-[YOUR_COMPONENT_NAME].scss

5. In src/components/instant-apps-[YOUR_COMPONENT_NAME]/instant-apps-[YOUR_COMPONENT_NAME].tsx, update the following:

@Component({
  tag: 'instant-apps-[YOUR_COMPONENT_NAME]',
  styleUrl: 'instant-apps-[YOUR_COMPONENT_NAME].css', <-- Update to .scss
  shadow: true,
})

More info on Stencil's CLI can be found here.

Writing Storybook stories

To include your web component in the storybook UI, create a .stories.ts file within your web component's directory i.e. src/components/instant-apps-[YOUR_COMPONENT_NAME]/instant-apps-[YOUR_COMPONENT_NAME].stories.ts.

Below is a code snippet example:

import { html } from 'lit-html';

export default {
  title: 'Component',
  argTypes: {
    exampleProp: { control: 'text' }
  },
};

const Template = ({ exampleProp }) =>
  html`<instant-apps-[YOUR_COMPONENT_NAME]
    example-prop="${exampleProp}"
  ></instant-apps-[YOUR_COMPONENT_NAME]>`;

export const Example = Template.bind({});

Example.args = { exampleProp: 'Example text.' };

More info on how to write stories can be found here.

Additionally, documenentation on how to provide controls to interact with the arguments of your web component dynamically can be found here.

Setting up the components in your project:

Managing assets:

In order for the library to work properly, you'll need to copy the assets to the root of your project.

For example:

ncp node_modules/@esri/instant-apps-components/dist/assets public/assets

Importing the components:

In your entry file (index.ts), simply import the component(s) into your project.

For example:

import "@esri/instant-apps-components/dist/components/instant-apps-header";
import "@esri/instant-apps-components/dist/components/instant-apps-social-share";

Contributing

We welcome contributions to this project. See CONTRIBUTING.md for an overview of contribution guidelines.

License

COPYRIGHT © 2024 Esri

All rights reserved under the copyright laws of the United States and applicable international laws, treaties, and conventions.

This material is licensed for use under the Esri Master License Agreement (MLA), and is bound by the terms of that agreement. You may redistribute and use this code without modification, provided you adhere to the terms of the MLA and include this copyright notice.

See use restrictions at http://www.esri.com/legal/pdfs/mla_e204_e300/english

For additional information, contact: Environmental Systems Research Institute, Inc. Attn: Contracts and Legal Services Department 380 New York Street Redlands, California, USA 92373 USA

email: [e-mail]