@ably/ui 中文文档教程

发布于 3年前 浏览 32 项目主页 更新于 3年前

注意:一些功能仍在开发中,它们的文档可能不完整。 注意 ⚠️ 图标。

ably-ui

ably-ui 是 Ably 设计系统库 (https://ably-ui.herokuapp. com/). 它为不同的可分发文件提供展示、开发/测试环境和发布管道。

Getting started

ably-ui 是一个基于核心网络技术支持各种网站/应用程序的库。 这就是为什么我们尽可能基于这些构建,但以一种易于使用我们在我们的属性中使用的框架的方式发布。

例如,Logo 组件有两个模板,用于 React 组件和 view-component 但使用相同的 CSS 类和相同的 JavaScript 挂钩 (data-id)。

在某些情况下,这是不切实际的。 一些组件将更加专业化并利用给定的框架,我们将不需要使其在多个框架中可用(例如,仅在已登录、类似 SPA 的区域中使用的某些组件)。

Guiding principles

  1. Provide easy access to common patterns and assets, from brand colours to navigation.
  2. Use the web platform as much as possible without relying on frameworks.
  3. Be flexible in how the library can be integrated.

Library structure

该库由模块、资产、JavaScript & 构建而成。 红宝石模块和组件。 模块是所有这些的容器。

例如,core 模块提供了可以构建基于 Web 界面的“chrome”的最通用元素——排版、颜色、间距(即容器)等。模块中的组件支持我们最常见的需求是构建“chrome”,如导航元素、页脚、英雄部分、代码示例等。资产、JavaScript 和; ruby 模块都是在模块中的组件之间共享的。

组件不直接需要资产——相反,由消费者加载资产并将它们传递给组件。 这确保了 URL 方面的灵活性。

除了组件之外,每个模块都公开了一个 scripts.jsstyles.cssMODULE_NAME.rb 文件。 scripts.js 包含辅助函数,MODULE_NAME.rb 包含组件可以包含的模块。 styles.css 包含不属于任何特定模块的 CSS。

Installation

NPM

这种类型的安装使您可以访问模块/组件资产以及 React 组件。

npm install @ably/ui

# or

yarn add @ably/ui

将导入的 JavaScript 从 Core 模块附加到 window 对象:

import "@ably/ui/core/scripts";

// AblyUi.Core is now available on window

导入 es6 core 模块并且不向 window 暴露任何内容:

import ablyUiCore from "@ably/ui/core/scripts";

导入Accordion 组件的 JavaScript:

import Accordion from "@ably/ui/core/accordion/component";

如果您的捆绑器支持 CSS 导入,您也可以导入它:

import "@ably/ui/core/styles.css";

Setting up TailwindCSS

目前,AblyUI CSS 构建为与 TailwindCSS 配合使用。 将其集成到您的应用程序中:

  1. Add AblyUI to your project
  2. Add TailwindCSS to your project https://tailwindcss.com/docs/installation#installing-tailwind-css-as-a-post-css-plugin
  3. Add the following to your tailwind.config.js. Note how different config properties are always extended by the ablyUIConfig:
const extendConfig = require("@ably/ui/tailwind.extend.js");

module.exports = extendConfig((ablyUIConfig) => ({
  ...ablyUIConfig,
  purge: {
    content: [
      ...(relative - globbed - paths - to - your - templates),
      ...ablyUIConfig.purge.content,
    ],
    options: {
      ...ablyUIConfig.purge.options,
    },
  },
}));
  1. In the CSS file you added your tailwind declarations too, import the CSS for the modules and components you need:
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

@import "@ably/ui/reset/styles.css"; /* needed as we disable the default Tailwind reset */
@import "@ably/ui/core/styles.css"; /* styles for core module components and more */
@import "@ably/ui/core/Meganav/component.css";
@import "@ably/ui/core/ContactFooter/component.css";

Importing React components

请注意,根据组件的不同,您可能仍需要包含 CSS & JS:

import Meganav from "@ably/ui/core/Meganav";

Importing ViewComponent (Rails) components

要将 ably-uiRuby on Rails 一起使用,请添加 ably-ui gem 到你的 Gemfile

gem 'ably-ui',
    '1.0.0',
    require: 'ably_ui'

组件显示为 View Components 并且应该在任何视图中可用:

<%= render(AblyUi::Core::Meganav.new) %>

注意这既不加载 CSS 也不加载 JS——这些仍然需要由像 webpack 这样的打包器加载。

Usage

Icons

将 SVG 文件放在 src/MODULE_NAME/icons 文件夹中会将它们添加到每个模块的精灵文件中,该文件将在模块的根目录下可用(例如,core/sprites.svg< /代码>)。 此文件可以使用 core 模块中可用的 loadSprites 帮助程序加载,或直接包含在页面中。

使用 Icon React 组件:

<Icon name="icon-display-live-chat" size="3rem" additionalCSS="block mb-16" />

使用 Icon VW 组件:

<%= render(AblyUi::Core::Icon.new(name: "icon-gui-disclosure-arrow", size: "1rem", additional_css: "align-middle transform rotate-180 mr-4")) %>

没有组件的

<!-- The width and height are required for correct sizing. The actual color class might depend on the svg and whether it uses strokes, fills etc. Note as well xlink:href, which is xlinkHref in react. -->
<svg class="w-12 h-12 text-cool-black">
  <use xlink:href="#sprite-disclosure-arrow" />
</svg>

使用:没有组件的使用,在 React 中,带有悬停状态。 注意 group 类:

<a
  href="{url}"
  className="text-gui-default hover:text-gui-hover focus:text-gui-focus group"
>
  {children}
  <svg className="w-12 h-12 transform -rotate-90 align-top ui-icon-dark-grey group-hover:icon-gui-hover group-focus:icon-gui-focus ml-4">
    <use xlinkHref="#sprite-disclosure-arrow" />
  </svg>
</a>

参见 https://ably-ui.herokuapp。 com/components/icon 了解更多详情。

Fonts

字体资产不是自动包含的,而是 repo 的一部分,还有一个字体文件示例; 有关示例,请参见 src/core/fonts。 确保包含有关使用的许可文件声明。

有关使用 webpacker/rails 的示例,请参见 preview/app/javascript/styles/application.css

Rails

因为 gem 目录位于资产路径上(参见 Importing ViewComponent (Rails) components 部分),它们将与标准资产助手一起工作(即 asset_path)。

Accessibility

ably-ui 的一个重要部分是确保生成的 UI 可供尽可能广泛的用户访问。 所有组件都应至少遵守 AA 可访问性标准。 在大多数情况下,这可以通过遵循一些简单的规则来实现:

— 使用正确的 HTML 元素< /a>:用于导航的锚点、用于交互的按钮、用于列表的列表等

  • test using a screen reader (for example Voice Over on a Mac OSX with Web rotor) — confirm designs have appropriate tap targets, contrast — use aria attributes where you reach the limits of what you can do with HTML — don't break the web platform (i.e., don't break the behaviour of a back button, scrolling, in-page links etc)

Development

该存储库包括一个“预览”应用程序,它既用作展示环境又用作开发环境。

要使用,首先确保为库和“预览”应用程序安装依赖项:

yarn && bundle
cd preview
yarn && bundle

然后,从存储库的根目录运行:

yarn dev

这将运行该应用程序并使用 ably-ui< 的已发布版本/code>,指定在preview/Gemfilepreview/package.json NPM包中。

Using the local ably-ui in the preview app

可以在“预览”应用程序中使用本地版本的 ably-ui。 启用此功能需要对 npmruby 包执行单独的步骤。

对于 npm

# in the root directory
yarn link
# in the the "preview" directory
yarn link @ably/ui

对于 ruby

preview/Gemfile 中替换 source: "https://rubygems.pkg.github.com/ ably"path: '../' 并运行:

# in preview
bundle --no-cache

Why not bundle config set local.ably-ui ../? 因为该功能是围绕本地 gem 构建的,它是一个单独的 repo,并且与我们的配置配合使用效果不佳。

这种方法的一个警告是不应提交更改 preview/Gemfile,因为它会导致远程应用程序无法构建。

Using a deployed package of ably-ui in the preview app

如果在任何时候你不想再使用本地 NPM 包和/或 gem,你可以这样做:

# in "preview" directory
yarn unlink @ably/ui

然后将 path 改回 source宝石文件。 如果您需要更新 Gemfile.lock 而不安装 gem,您可以运行 bundle lock

Publishing pre-release packages for review apps

确保你提交 & 在执行此操作之前,推送您的工作并删除特定于开发的配置

您需要使用 npmjsRuby Gems 发布。

完成上述操作后,您应该:

  • NPM_TOKEN set in your environment
  • .npmrc file to read NPM_TOKEN from your environment like this:
  //registry.npmjs.org/:_authToken=${NPM_TOKEN}
  • a ~/.gem/credentials file that has your Rubygems API key:
  ---
  :rubygems_api_key: REPLACE_THIS_WITH_YOUR_OWN_API_KEY

要使用正在进行的代码部署评论应用程序,您可以使用 pre-release 脚本:

# in root
./pre-release

这将做几件事:

- 更新您的本地依赖 项ably-ui 并运行生产构建 — 发布一个 gem 和一个 NPM 包,其中包含从当前 SemVer 构建的版本,但添加基于 HEAD 提交的短 SHA 的预发布标签

  • update the preview app
  • commit all the above and push to origin

这将触发审查应用程序的构建。

Components

组件和模块包含 JS 和 CSS 文件,但没有模板。 相反,对于给定组件支持的每个框架,都会创建一个单独的“框架模板”。 一个组件仍然可以通过使用它所需的资产在任何其他框架中使用。

所有组件都位于 src 中并遵循目录和文件名约定:

  • module directory (TitleCase)
  • module asset files: scripts.js for JavaScript and styles.css for CSS
  • component directory (TitleCase)
    • component.js - this is the entry file for a component and is the only required file
    • components.css - additional CSS
    • for ruby components, you need component.rb and component.html.erb
    • for react, components.jsx

例如:

- Core
  - script.js
  - styles.css
  - Accordion
    - component.rb
    - component.html.erb
    - component.js
    - component.css
    - component.jsx

CSS

z-index and positioning

如果使用除静态之外的定位,请注意创建堆栈上下文。 在 properties.css 中,您会找到 HTML 堆栈上下文的 z-index 值(由 meganav 等组件使用)。 在您的组件中创建一个新的时,将 z-index 值提升到创建堆叠上下文的选择器,并在那里定义 z-index 值以便于扫描(请参阅 https://www.oreilly。 com/library/view/developing-web-components/9781491905685/ch04.html 以获得关于堆叠上下文和 z-index 的精彩文章。)

Formatting & linting files

默认情况下,Prettier & ESLint 将处理大部分前端文件。 您可以通过您的编辑器(它应该获取相关的配置文件)或在命令行上使用它们(请参阅 package.json 中的 scripts)。

两者都不处理 erbrb 文件。 这些文件的唯一配置目前在 editorconfig 中。

Note

在我们为 erb 设置格式化脚本之前,值得为您的编辑器设置 htmlbeautifier(例如https://github.com/aliariff/vscode-erb-beautify 如果你使用 VS 代码)并跟踪这个问题在Prettier,因为 Prettier 速度更快,并且有望获得对 erb 的支持。

Adding a new component

To add a new component:

  1. Add it in modules-config.js
  2. Create a folder in src, in the module of your choice. The folder name should be TitleCase.
  3. Add a component.js
  • if the component has custom CSS, add a component.css file as well. Add @layer components {} to its contents. Import the CSS file in component.js
  • if you need a VW component, add component.rb and component.html.erb
  • if you need a React component, add a components.jsx

To see this component in the preview app:

For React components:
  1. Import the file into preview/app/javascript/packs/application.js and add as input to the reactRenderer
  2. If it contains custom CSS, import it into preview/app/javascript/styles/application.css
  3. Add a template in preview/app/views/components, with a _react suffix, i.e. my_component_react.html.erb
For VW components:
  1. You will need to restart the server for Rails to load the component (this will also need to happen after any changes to component.rb)
  2. If it contains custom CSS, import it into preview/app/javascript/styles/application.css
  3. Add a template in preview/app/views/components, with a _vw suffix, i.e. my_component_vw.html.erb
  4. If the component has any JavaScript, import it in the view (preview/app/views/components/my_component_vw.html.erb) and initialize:
<% content_for :component do %>
  <%= javascript_include_tag 'ably_ui/core/my_component/component' %>
  <script type="text/javascript">
    document.addEventListener("DOMContentLoaded", () => {
      const container = document.querySelector("[data-id=my_component]");
      AblyUI.Core.MyComponent(container);
    });
  </script>
<% end %>

Publishing

我们使用 Semantic Versioning 2.0.0 来控制不同的库版本。

包发布到 GitHub 私有注册表

发布是通过在 GitHub 中标记发布来完成的。 这会触发一个 GitHub 操作,该操作会推送到私有 NPM 和 gem 注册表,并在 CDN 中发布新的工件,版本从 GitHub 发布的标签中获取。 ⚠️

这将在支持的应用程序中触发 GitHub 操作(目前 Voltaire & Website) 创建带有 ably-ui 版本更新的 PR。

触发发布:

  • Merge your PR into main.
  • On the Github Ably-UI repo, create a new release tag.
  • Create a new tag with the new version number for the release.
  • Do not prefix the tag with a v
  • Add a meaningful title for the Release.
  • Click on the Autogenerate release notes button.
  • Publish Release.

这将发布包、更新库和; 预览应用程序并创建 & 推送提交 & tag,也可以在 Voltaire & 中创建相应的 PR 网站。

Running tests

该存储库包括用于快照、屏幕截图、奇偶校验和行为测试的 Cypress。 赛普拉斯针对“预览”服务器运行(例如用于开发的同一台服务器)。

快照测试 保存 DOM 并在运行之间进行比较 - 快照更新可以在 Cypress UI 中完成。

屏幕截图测试 获取组件的屏幕截图并在运行之间进行比较。 差异位于 cypress/screenshots。 要更新屏幕截图,请将其删除。

奇偶校验 检查 VW/React 组件; 屏幕截图是两个版本的截图,如果它们不同则失败。

行为测试 在 DOM 周围点击并检查要更新的页面上的单个元素。

要运行集成测试(使用 Cypress),您需要在端口 5000 上运行“预览应用”,然后运行

yarn cy:open

:将打开 Cypress 的 UI,您可以从中运行测试。 屏幕截图保存在 cypress/screenshots 中。

Note: some features are still in development and their documentation might be incomplete. Lookout for the ⚠️ icon.

ably-ui

ably-ui is the of home of the Ably design system library (https://ably-ui.herokuapp.com/). It provides a showcase, development/test environment and a publishing pipeline for different distributables.

Getting started

ably-ui is a library built in mind with supporting a variety of websites/apps based on core web technologies. That's why where possible we build based on those but publish in a way that is easy to consume for frameworks we use across our properties.

As an example, the Logo component has two templates, for a React component and view-component but uses the same CSS classes and same JavaScript hooks (data-id).

In some cases, this is impractical. Some components will be more specialized and take advantage of a given framework, and we will have no need to make it available in multiple frameworks (for example, something that is only used within signed in, SPA like areas).

Guiding principles

  1. Provide easy access to common patterns and assets, from brand colours to navigation.
  2. Use the web platform as much as possible without relying on frameworks.
  3. Be flexible in how the library can be integrated.

Library structure

The library is built out of modules, assets, JavaScript & ruby modules and components. A module is a container for all of those.

For example, the core module provides the most general elements one can build the “chrome” of a web-based interface — typography, colours, spacing (i.e., containers) etc. The components within the module support our most common needs to build that “chrome”, like navigation elements, footer, hero sections, code samples etc. Assets, JavaScript & ruby modules are all shared between the components in the module.

Components do not require assets directly — instead, it's up to the consumer to load the assets and pass them to the components. This ensures flexibility in terms of URLs.

Each module, apart from components, exposes a scripts.js, styles.css and MODULE_NAME.rb files. scripts.js contains helper functions, MODULE_NAME.rb contains modules that components can include. styles.css contains CSS that does not belong to any module in particular.

Installation

NPM

This type of installation gives you access to module/components assets as well as React components.

npm install @ably/ui

# or

yarn add @ably/ui

To attach the imported JavaScript from the Core module to the window object:

import "@ably/ui/core/scripts";

// AblyUi.Core is now available on window

To import an es6 core module and expose nothing to window:

import ablyUiCore from "@ably/ui/core/scripts";

To import the JavaScript for an Accordion component:

import Accordion from "@ably/ui/core/accordion/component";

If your bundler supports CSS importing, you can import it as well:

import "@ably/ui/core/styles.css";

Setting up TailwindCSS

Currently, AblyUI CSS is built to work with TailwindCSS. To integrate it into your app:

  1. Add AblyUI to your project
  2. Add TailwindCSS to your project https://tailwindcss.com/docs/installation#installing-tailwind-css-as-a-post-css-plugin
  3. Add the following to your tailwind.config.js. Note how different config properties are always extended by the ablyUIConfig:
const extendConfig = require("@ably/ui/tailwind.extend.js");

module.exports = extendConfig((ablyUIConfig) => ({
  ...ablyUIConfig,
  purge: {
    content: [
      ...(relative - globbed - paths - to - your - templates),
      ...ablyUIConfig.purge.content,
    ],
    options: {
      ...ablyUIConfig.purge.options,
    },
  },
}));
  1. In the CSS file you added your tailwind declarations too, import the CSS for the modules and components you need:
@import "tailwindcss/base";
@import "tailwindcss/components";
@import "tailwindcss/utilities";

@import "@ably/ui/reset/styles.css"; /* needed as we disable the default Tailwind reset */
@import "@ably/ui/core/styles.css"; /* styles for core module components and more */
@import "@ably/ui/core/Meganav/component.css";
@import "@ably/ui/core/ContactFooter/component.css";

Importing React components

Note that depending on the component, you might still need to include CSS & JS for it:

import Meganav from "@ably/ui/core/Meganav";

Importing ViewComponent (Rails) components

To use ably-ui with Ruby on Rails add the ably-ui gem to your Gemfile:

gem 'ably-ui',
    '1.0.0',
    require: 'ably_ui'

Components are exposed as View Components and should be available in any view:

<%= render(AblyUi::Core::Meganav.new) %>

Note that this loads neither CSS nor JS — these need to still be loaded by a bundler like webpack.

Usage

Icons

Putting SVG files inside and src/MODULE_NAME/icons folder will add them to a per-module sprites file that will be available at the root of the module (e.g., core/sprites.svg). This file can be loaded with the loadSprites helper available in the core module or include in the page directly.

Usage with the Icon React component:

<Icon name="icon-display-live-chat" size="3rem" additionalCSS="block mb-16" />

Usage with Icon VW component:

<%= render(AblyUi::Core::Icon.new(name: "icon-gui-disclosure-arrow", size: "1rem", additional_css: "align-middle transform rotate-180 mr-4")) %>

Usage without a component:

<!-- The width and height are required for correct sizing. The actual color class might depend on the svg and whether it uses strokes, fills etc. Note as well xlink:href, which is xlinkHref in react. -->
<svg class="w-12 h-12 text-cool-black">
  <use xlink:href="#sprite-disclosure-arrow" />
</svg>

Usage without a component, in React, with hover states. Note the group class:

<a
  href="{url}"
  className="text-gui-default hover:text-gui-hover focus:text-gui-focus group"
>
  {children}
  <svg className="w-12 h-12 transform -rotate-90 align-top ui-icon-dark-grey group-hover:icon-gui-hover group-focus:icon-gui-focus ml-4">
    <use xlinkHref="#sprite-disclosure-arrow" />
  </svg>
</a>

See https://ably-ui.herokuapp.com/components/icon for more details.

Fonts

Font assets are not included automagically but are part of the repo, together with an example of font-face file; see src/core/fonts for examples. Make sure to include the licence file declaration on usage.

See preview/app/javascript/styles/application.css for an example when using webpacker/rails.

Rails

Because the gem directories are on the asset path (see Importing ViewComponent (Rails) components section), they will work with standard asset helpers (i.e., asset_path).

Accessibility

An important part of ably-ui is ensuring the produced UI is accessible to as wide range of users as possible. All components should adhere to at least AA accessibility standards. In most cases, this can be accomplished by following a few simple rules:

— use the correct HTML elements: anchors for navigation, buttons for interacting, lists for lists etc

  • test using a screen reader (for example Voice Over on a Mac OSX with Web rotor) — confirm designs have appropriate tap targets, contrast — use aria attributes where you reach the limits of what you can do with HTML — don't break the web platform (i.e., don't break the behaviour of a back button, scrolling, in-page links etc)

Development

The repository includes a “preview” app, which is serves both as a showcase and development environment.

To use, first make sure you install dependencies both for the library and the “preview” app:

yarn && bundle
cd preview
yarn && bundle

Then, from the root of the repository, run:

yarn dev

This will run the app and use the published versions of the ably-ui, specified in preview/Gemfile and preview/package.json NPM package.

Using the local ably-ui in the preview app

It's possible to use the local version of ably-ui in the “preview” app. Enabling this, requires separate steps for the npm and ruby packages.

For npm:

# in the root directory
yarn link
# in the the "preview" directory
yarn link @ably/ui

For ruby:

In preview/Gemfile replace source: "https://rubygems.pkg.github.com/ably" with path: '../' and run:

# in preview
bundle --no-cache

Why not bundle config set local.ably-ui ../? Because that feature is built around the local gem being a separate repo, and works poorly with our config.

A caveat of this approach is that the change preview/Gemfile should not be committed, as it will cause the remote app to not build.

Using a deployed package of ably-ui in the preview app

If at anytime you don't want to use the local NPM package and/or gems any more, you can do:

# in "preview" directory
yarn unlink @ably/ui

Then change back path to source source in the Gemfile. If you need to update Gemfile.lock without installing gems, you can run bundle lock.

Publishing pre-release packages for review apps

Make sure you commit & push your work and remove the development-specific config before doing this.

You will need to authenticate with npmjs and Ruby Gems to publish.

After the above, you should have:

  • NPM_TOKEN set in your environment
  • .npmrc file to read NPM_TOKEN from your environment like this:
  //registry.npmjs.org/:_authToken=${NPM_TOKEN}
  • a ~/.gem/credentials file that has your Rubygems API key:
  ---
  :rubygems_api_key: REPLACE_THIS_WITH_YOUR_OWN_API_KEY

To deploy a review app with your in-progress code, you can use the pre-release script:

# in root
./pre-release

This will do a couple of things:

— update your local dependencies for ably-ui and run a production build — release a gem and a NPM package with the version built from your current SemVer but adding a pre-release tag based on a short SHA of your HEAD commit

  • update the preview app
  • commit all the above and push to origin

This will trigger a build of the review app.

Components

Components and modules contain JS and CSS files, but no templates. Instead, for each framework that a given component supports, a separate "framework template" is created. A component can still be used in any other framework by just using it's required assets.

All components live in src and follow a directory and filename convention:

  • module directory (TitleCase)
  • module asset files: scripts.js for JavaScript and styles.css for CSS
  • component directory (TitleCase)
    • component.js - this is the entry file for a component and is the only required file
    • components.css - additional CSS
    • for ruby components, you need component.rb and component.html.erb
    • for react, components.jsx

For example:

- Core
  - script.js
  - styles.css
  - Accordion
    - component.rb
    - component.html.erb
    - component.js
    - component.css
    - component.jsx

CSS

z-index and positioning

If using positioning any other than static, be mindful of creating stacking contexts. In properties.css you'll find the z-index values for the HTML stacking context (used by components like the meganav). When creating a new one within your component, hoist the z-index values to the selector that creates the stacking context and define z-index values there for easy scanning (see https://www.oreilly.com/library/view/developing-web-components/9781491905685/ch04.html for a good write-up on stacking contexts and z-index.).

Formatting & linting files

By default, Prettier & ESLint will handle most of the frontend files. You can use them through your editor (which should pick up the relevant config files) or on the command line (see scripts in package.json).

Neither handles erb and rb files. The only config for those files is at the moment in editorconfig.

Note

Until we have set up formatting scripts for erb it's worth setting up htmlbeautifier for your editor (for example with https://github.com/aliariff/vscode-erb-beautify if you use VS Code) and tracking this issue in Prettier, as Prettier is much faster and hopefully will get support for erb.

Adding a new component

To add a new component:

  1. Add it in modules-config.js
  2. Create a folder in src, in the module of your choice. The folder name should be TitleCase.
  3. Add a component.js
  • if the component has custom CSS, add a component.css file as well. Add @layer components {} to its contents. Import the CSS file in component.js
  • if you need a VW component, add component.rb and component.html.erb
  • if you need a React component, add a components.jsx

To see this component in the preview app:

For React components:
  1. Import the file into preview/app/javascript/packs/application.js and add as input to the reactRenderer
  2. If it contains custom CSS, import it into preview/app/javascript/styles/application.css
  3. Add a template in preview/app/views/components, with a _react suffix, i.e. my_component_react.html.erb
For VW components:
  1. You will need to restart the server for Rails to load the component (this will also need to happen after any changes to component.rb)
  2. If it contains custom CSS, import it into preview/app/javascript/styles/application.css
  3. Add a template in preview/app/views/components, with a _vw suffix, i.e. my_component_vw.html.erb
  4. If the component has any JavaScript, import it in the view (preview/app/views/components/my_component_vw.html.erb) and initialize:
<% content_for :component do %>
  <%= javascript_include_tag 'ably_ui/core/my_component/component' %>
  <script type="text/javascript">
    document.addEventListener("DOMContentLoaded", () => {
      const container = document.querySelector("[data-id=my_component]");
      AblyUI.Core.MyComponent(container);
    });
  </script>
<% end %>

Publishing

We use Semantic Versioning 2.0.0 to version different library versions.

Packages are published to the GitHub private registry.

Publishing is done by tagging a release in GitHub. This triggers a GitHub action that pushes to the private NPM and gem registries as well as publishing new artefacts in the CDN, with the version taken from the tag of the GitHub release. ⚠️

This will trigger GitHub actions in supported apps (currently Voltaire & Website) to create a PR with an ably-ui version update.

To trigger a release:

  • Merge your PR into main.
  • On the Github Ably-UI repo, create a new release tag.
  • Create a new tag with the new version number for the release.
  • Do not prefix the tag with a v
  • Add a meaningful title for the Release.
  • Click on the Autogenerate release notes button.
  • Publish Release.

This will release the packages, update library & preview app and create & push the commit & tag, and also create corresponding PRs in Voltaire & Website.

Running tests

The repo includes Cypress for snapshot, screenshot, parity and behaviour testing. Cypress runs against the "preview" server (e.g. the same server used for development).

Snapshot testing takes saves the DOM and compares it between runs - updating of snapshots can be done in the Cypress UI.

Screenshot testing takes a screenshot of a component and compares it between runs. Diffs are located in cypress/screenshots. To update a screenshot, delete it.

Parity testing checks VW/React components; screenshots are taken of both versions and fail if they are different.

Behaviour testing clicks around the DOM and checks for singular elements on the page to be updated.

To run integration tests (using Cypress), you'll need to have the "preview app" running on port 5000, then run:

yarn cy:open

This will open the UI for Cypress, from which you can run the tests. Screenshots are saved in cypress/screenshots.

    我们使用 Cookies 和其他技术来定制您的体验包括您的登录状态等。通过阅读我们的 隐私政策 了解更多相关信息。 单击 接受 或继续使用网站,即表示您同意使用 Cookies 和您的相关数据。
    原文