qiskit / web-components

Qiskit Web Components

Important

This repository is unmaintained and the content in qiskit.org has been superseded by the IBM Quantum | Community page. These source files are no longer maintained and may contain omissions or outdated information. Contributions to this repo are no longer accepted.

Qiskit Components

Qiskit Components is a future-looking project to develop Qiskit design system based around Web Components, ES Modules, and modern browser standards.

Usage

Prerequisites

• Node.js v16 or later.

Install

npm install @qiskit/web-components

Example

import '@qiskit/web-components/banner';

<qiskit-banner>We have an important announcement!</qiskit-banner>

Contributing

Prerequisites

• Node.js v16 or later.

Furthermore, this project is built on TypeScript with the intention of improving the developer experience.

Install the dependencies

npm install

Start the development server (with Storybook)

This command serves the app at http://localhost:8000:

npm start

Running the tests

This command runs the tests:

npm test

web-components's Issues

Bug: Overview link in documentation dropdown doesn't direct to overview

Steps to reproduce the problem

1. go to qiskit.org
2. click on documentation in the top menu
3. when the documentation menu expands, go to the left, click the "overview" link under getting started
4. this link directs users to the "getting started" page rather than the overview page

What is the current behavior?

the overview link directs users to the getting started page in the qiskit documentation

What is the expected behavior?

the overview link should go to the the overview page of the qiskit documentation (https://qiskit.org/documentation/index.html)

I think it would also be good if we could add a heading in that section specifically directing users to the getting started page

Screenshots

No response

Device

No response

OS

No response

Browser

No response

Additional information

No response

Replace Aer provider link in top menu

When Qiskit Aer v0.12 is released it will start building and deploying it's own documentation, meaning we should update the top menu link to reflect this change (currently it points to the metapackage aer docs)

[Mega Menu UI] `MegaMenuDropdown` icon spacing and position

Steps to reproduce the problem

Have a look at the MegaMenuDropdown on the Feature Learn Content branch

What is the current behavior?

• the down chevron icon isn't vertically centered
• there's not enough spacing/padding, to the right of the down chevron icon

What is the expected behavior?

• centered vertically (like qiskit.org/textbook-beta shows today)
• slightly more spacing to right of the icon

Screenshots

CC: @JRussellHuffman

[UI-Shell] axe landmark-contentinfo-is-top-level failure

Steps to reproduce the problem

In platypus ui-shell integration PR, remove disabled rule and run npm run test and see failures.

Rule link

Changing the sidenav social icon <footer> to a regular <div> will resolve the problem

1 accessibility violation was detected
{
  id: 'landmark-contentinfo-is-top-level',
  impact: 'moderate',
  tags: [ 'cat.semantics', 'best-practice' ],
  description: 'Ensures the contentinfo landmark is at top level',
  help: 'Contentinfo landmark should not be contained in another landmark',
  helpUrl: 'https://dequeuniversity.com/rules/axe/4.4/landmark-contentinfo-is-top-level?application=axeAPI',
  nodes: [
    {
      any: [Array],
      all: [],
      none: [],
      impact: 'moderate',
      html: '<footer class="qiskit-side-nav-footer">',
      target: [Array],
      failureSummary: 'Fix any of the following:\n' +
        '  The null landmark is contained in another landmark.'
    }
  ]
}
┌─────────┬─────────────────────────────────────┬────────────┬────────────────────────────────────────────────────┬───────┐
│ (index) │                 id                  │   impact   │                    description                     │ nodes │
├─────────┼─────────────────────────────────────┼────────────┼────────────────────────────────────────────────────┼───────┤
│    0    │ 'landmark-contentinfo-is-top-level' │ 'moderate' │ 'Ensures the contentinfo landmark is at top level' │   1   │
└─────────┴─────────────────────────────────────┴────────────┴────────────────────────────────────────────────────┴───────┘
    1) has no detectable violations on load


  0 passing (9s)
  1 failing

  1) Accessibility
       has no detectable violations on load:
     AssertionError: 1 accessibility violation was detected: expected 1 to equal 0
      at Context.eval (http://localhost:8080/__cypress/tests?p=cypress/support/index.js:797:20)

What is the current behavior?

Running platypus cypress tests fails accessibility spec with new ui-header component

What is the expected behavior?

The existing a11y tests should pass

Screenshots

Device

No response

OS

No response

Browser

No response

Additional information

Changing the sidenav social icon <footer> to a regular <div> will resolve the problem

Contributing.MD file missing

Feature description

I noticed that CONTRIBUTING.md file is missing in this repo.

I think this is the main reason why their aren't much contributors here.

And this is quite a great project.

Adding this file would attract first timers and would push the contribution to a greater length.

This is just suggestion, please what do you think?

Additional context

No response

Linter import error

Hi, so when running npm run lint in #67 we have the following error:

However if we look inside lit standar docs, we can see that TemplateResult is indeed inside lit...

[Navbar] "Get started" should be "Getting Started"

Steps to reproduce the problem

1. Go to https://qiskit.org/
2. Click "Documentation" dropdown menu

What is the current behavior?

"Get started"

What is the expected behavior?

"Getting Started" to matched with the linked page: https://qiskit.org/documentation/getting_started.html

"S" should be capitalized to match the style of "Help and Learning"

Screenshots

No response

Device

No response

OS

No response

Browser

No response

Additional information

No response

[Navbar] Should the Slack link be the invitation link on mega dropdown menu?

Steps to reproduce the problem

1. Go to https://qiskit.org/
2. Click "Documentation" dropdown menu
3. Check the link for "Slack"

What is the current behavior?

The current link is https://qiskit.slack.com/

What is the expected behavior?

We have been using https://ibm.co/joinqiskitslack (which is a bit.ly link for the Slack invitation) for the link to Slack so that new users can also join. The current link https://qiskit.slack.com/ only works for users that already joined Slack.

But I know there is also discussions about reducing the number of users to our Slack so this link https://qiskit.slack.com/ could be a better link.

cc: @lerongil @1ucian0

Screenshots

No response

Device

No response

OS

No response

Browser

No response

Additional information

No response

Implement Segment tracking events in Navbar links

Feature description

After implementing the Documentation Dropdown in the Navbar web component, we need to also ensure that all links send the appropriate Segment tracking events when clicked.

For this, we need to consider that now we'll be able to have one unified navbar / header for all Qiskit websites.

Dependencies

This task depends on:

• #100

Additional context

• We need to work closely with @agebbie to provide the data in the most useful format possible.
• We need to coordinate with @korgan00 to have a consistent approach to triggering tracking events here and in the widgets.

[UI Shell] Make base url for nav items dynamic

Feature description

The current implementation of the ui-shell (navbar) uses absolute URLs for each navigation item. We would like to explore an alternative approach that would allow us to stay in context of the current environment. For example, when testing a branch preview, clicking the account icon would maintain the base preview URL instead of navigating to the live prod build.

Related comment Qiskit/platypus#1555 (review)

After internal discussions, we would like to try something to the logic below 👇

const BASE_URL = window.origin === 'https://learn.qiskit.org/'
    ? 'https://qiskit.org/'
    : window.origin;

Additional context

The decision to use the absolute URL was to avoid any issues specifically when users are in the textbook/platypus experience since the textbook pages have the learn. subdomain.

Also should consider how these changes may affect documentation platform

Slack discussion

Add "Ecosystem" link

Feature description

We need to add the "Ecosystem" link in the "Community" dropdown, pointing to https://qiskit.org/ecosystem/.

Alternatives

No response

Additional context

After creating the new "ecosystem" page, the link was added to the header. We need to update the web component accordingly.

Create a Card component

Feature description

To accommodate for the Curated Syllabi designs, we'll be needing a consistent Card component that will be used across multiple projects — qiskit org, platypus (for now), and later on saiba.

Acceptance criteria

• Card should have a body that allows for content
• Card should have option for single action (button)
• Card should have option for a set of actions

Additional context

No response

Improve README with instructions for projects other than node based ones

Feature description

It would be great if the README had instructions for how to use these components in other environments other than npm based projects.

Additional context

For example I am trying to implement the main top menu bar in a basic html file and not sure how to proceed 😅

[Navigation UI] User Account text not showing up

Steps to reproduce the problem

Resize the NavBar component until the navBar is collapsed. Then open the menu with the hamburguer button.

What is the current behavior?

The text of the user account button is not displayed. Also the colors of the user icon and backgorund color are inverted (the first must be purple the second must be white).

What is the expected behavior?

It should say "Account" and the colors should be inverted.

Screenshots

Device

No response

OS

No response

Browser

Chrome

Additional information

No response

Create footer web component

We need to recreate the footer currently available in qiskit.org as a web component to reuse it in multiple projects.

Change the link of `Qiskit IBM Provider` to the new `qiskit-ibm-provider` doc

Feature description

Currently Qiskit IBM Provider in the mega dropdown menu is linked to the old qiskit-ibmq-provider doc (part of the qiskit meta doc). The old provider is going to be deprecated and replaced by the new qiskit-ibm-provider soon. With that, I think we should replace the link in the mega dropdown menu to the new provider doc: https://qiskit.org/documentation/partners/qiskit_ibm_provider/

FYI @1ucian0 @kt474 @jyu00

Additional context

No response

[Navbar UI] Transparent background

Steps to reproduce the problem

1. visit any saiba page that has enough content to warrant a vertical scroll
2. see error

What is the current behavior?

the main site nav has a transparent background, allowing content to be visible through the nav

What is the expected behavior?

the main site nav should have a defined background-color

Additional information

Originally reported by @techtolentino in https://github.com/Qiskit/saiba/issues/120

Screenshots

Screen.Recording.2022-08-24.at.1.01.26.PM.mov

Device

No response

OS

No response

Browser

No response

Additional information

No response

Textbook Versioning

Feature description

This feature gives the user the ability to change to a different version of the textbook, as well as view the change log to understand what has changed on the textbook. The designs are complete.

areas of change include:

• learn page versioning next to the "browse all content". this will scroll next to the "browse all content" down the page
• versioning will be available on the individual textbook pages on the left next to the "browse all content"

https://www.figma.com/file/s94cmNVUcbFnTEbasdPNgN/1476-textbook-content-versioning?node-id=209%3A3177&t=rmG6WTM4svKq33JW-1

Additional context

No response

Bug: Typo for "Qiskit Textbook" in mega dropdown menu

Steps to reproduce the problem

1. Go to https://qiskit.org/
2. Click "Documentation" drop down menu
3. See "Qiskit textboox"

What is the current behavior?

"Qiskit Textbook" is spelled "Qiskit textboox"

What is the expected behavior?

The correct spelling should be "Qiskit Textbook" and "T" should be capitalized to follow the style of other links listed in the dropdown menu.

Screenshots

No response

Device

No response

OS

No response

Browser

No response

Additional information

No response

Add "Documentation" dropdown to Navbar

Feature description

We need to update the main navigation bar (aka Navbar) to replace the current "Documentation" link with a "Documentation" dropdown that shows various links to documentation pages.

We could try and use the "Masthead" Carbon for IBM.com component if possible, or maybe at least take some inspiration from its implementation.

Dependencies

This issue depends on:

• https://github.com/Qiskit/saiba/issues/134

Ressources

• Design: https://www.figma.com/file/xc1jekL6jga6NyRH64k1mV/documentation-redesign?node-id=136%3A1821
• Prototype: https://www.figma.com/proto/xc1jekL6jga6NyRH64k1mV/documentation-redesign?page-id=152%3A1426&node-id=179%3A1819&viewport=335%2C-122%2C0.34&scaling=min-zoom&starting-point-node-id=179%3A1819&show-proto-sidebar=1

Design capture

Additional context

• Please reach out to @JRussellHuffman for any questions on the design.
• Carbon for IBM.com's Masthead web component: https://github.com/carbon-design-system/carbon-for-ibm-dotcom/tree/main/packages/web-components/src/components/masthead

Add User Account button to the Navbar component

Following a discussion/question initiated by @JRussellHuffman — the UserAccount UI element in the header should be available from https://qiskit.org/textbook-beta.

For the most consistent UI experience, the Navbar component here could be updated to include the UserAccount button, then, the Navbar can be consumed by both the Platypus and Qiskitorg projects.

Mega dropdown menu navigation

Feature description

#140 added an awesome dropdown menu for documentation. It's great to have this unified top menu with additional links. However, after trying it a bit, I realized the user experience of getting to the documentation homepage is actually worse.

Previously users can go to the documentation homepage with one click on the "Documentation" menu item. Now they need to click on it, move the cursor all the way across the screen and click "Overview" under "Get started". That's two clicks and a lot of mouse movement.

Suggestion

Would it be possible to split the action for the linked text and the dropdown arrow for "Documentation" on the top menu? That means when a user clicks on the text "Documentation", they will go to documentation homepage https://qiskit.org/documentation/ just like in the past, but when they click on the arrow "^" it opens the dropdown menu.

This possibly violate some web design principles. I mainly want to bring up this issue, and hope we can find a good solution :D

Additional context

No response

Update link to Aer documentation homepage after Aer 0.11 release

Feature description

Following up from #140 (comment), since #140 is already merged. Creating this issue to keep track.

With Aer 0.11 release (coming soon), aer documentation will have it's own page. Depending on when this PR is merged, we should change the link to https://qiskit.org/documentation/aer

web-components/components/ui-shell/settings.ts

Lines 70 to 72 in 27cc6ee

	label: 'Qiskit Aer',
	url: 'https://qiskit.org/documentation/apidoc/aer.html',
	},

Additional context

No response

Fix node engine warning

When you use the library in a project that is not using Node v16 we have this warning:

npm WARN notsup Unsupported engine for @qiskit/[email protected]: wanted: {"node":"16.x"} (current: {"node":"14.17.5","npm":"6.14.15"})
npm WARN notsup Not compatible with your version of node/npm: @qiskit/[email protected]

We should fix this with a more open engine range or removing it.

Support content changes in Mega Menu

With the new Learn content being available on Qiskit.org's site, we'll need to update the MegaMenu dropdown to handle the new content structure.

Designs shown here

• MegaMenu should have section titles
• MegaMenu should not have hard-coded menu links

As a learning, I want to access the written material associated with "Single Systems" video lecture.

Have a general "support channels" instead of QCSE direct link

In many places in qiskit.org and other IBM products, we are sending users to http://quantumcomputing.stackexchange.com/ when they have general questions. However, the QCSE forum is designed to focus on a very specific list of topics and many of the questions that users (specially newcomers) make there end up being closed as off-topic.

I think we should give more context on the kind of question that should go to QCSE and present alternatives to users on how to get support (such as documentation site or slack).

At the moment, the closest we have to such a general support channel index is https://qisk.it/support. I suggest to change the footer to replace Stack Exchange for Support channels linking to https://qisk.it/support.

Ditto, the top bar.

This issue was thought in collaboration with @Eric-Arellano and it is part of this user-story.

For more context, see:

• https://chat.stackexchange.com/transcript/message/63125058#63125058
• https://quantumcomputing.meta.stackexchange.com/a/524/1859

[UI-Shell] Tab navigation of Navbar includes hidden elements

Steps to reproduce the problem

1. Open the Navbar on a desktop-sized viewport
2. Use the tab to navigate thought the Navbar links and see the target links
3. Move to the next element after "Documentation" with the tab key
4. See how hidden links from the mobile menu are being selected (like overview)

What is the current behavior?

Hidden links are accessible via tab.

What is the expected behavior?

Hidden links (like the links from the mobile menu when on a desktop-sized viewport) should not be accessible via tabs.

Screenshots

In this screen recording, I change the link to the overview page that should only be accessible in the mobile menu.

Then I use tabs to navigate the Navbar.

Please watch the target links at the bottom of the window when I select a new link from the Navbar, and see how after I select Dropdown, the overview link from the mobile menu is selected, even thought the mobile menu should be invisible / inaccessible in this viewport.

Screen.Recording.2022-09-15.at.13.44.53.mov

Device

MacBook Pro

OS

MacOS

Browser

Chrome

Additional information

No response

Externalize course list from mega-menu-dropdown

Remove providers column on mega drop down menu

Feature description

A new qiskit.org/providers page will be added by Qiskit/qiskit.org#2855 and Providers item will be promoted to the top level on the top menu (#207). We should remove the providers column on the mega drop down menu

cc: @1ucian0 @techtolentino

Additional context

No response

Bug: `MegaMenuDropdown` background-color on small viewports

Steps to reproduce the problem

View the qiskit-mega-menu-dropdown on small viewports

What is the current behavior?

The input field bg color is transparent

What is the expected behavior?

It should be allowed to be overridden so that a consuming project can set it to white (use case needed for qiskit.org)

Screenshots

RPReplay_Final1654554800.MP4

Bug: image not showing in `MegaMenuDropdown`

Steps to reproduce the problem

• Visit the MegaMenuDropdown in the storybook
• type in the word test (or any string that won't exist in the results)

What is the current behavior?

The image is not found

What is the expected behavior?

There should be an image showing

Screenshots

(Same happens when implemented in Qiskit project)

Device

No response

OS

No response

Browser

No response

Additional information

No response

Create new ErrorPage component

Feature description

We currently have a 404 page in the Textbook beta project — you can see it here https://learn.qiskit.org/test-page

The qiskit org project needs an error page, though we don't have one.

This feature request would be to take what exists in the Textbook beta project, and create a reusable page component that can be used in both projects, therefore giving our users consistency across both experiences.

Screenshot

Additional context

No response

Create a Carbon Data Table component

We need to create a component that is basically the Carbon Data Table component, but styled for Qiskit.

For reference, we can take the current style of the tables in qiskit.org.

Replace Slack invite link to https://qisk.it/join-slack

Feature description

The current Slack invite link https://ibm.co/joinqiskitslack is being replaced by https://qisk.it/join-slack to use the Qiskit brand name. We should use the new link for qiskit.org.

Related to Qiskit/qiskit.org#2959

cc: @paulsearle

Additional context

No response

Hamburguer button doesn't work

The hamburguer button of the navBar component doesn't do anything on click.
How to reproduce?

• Enter the NavBar component from your browser
• Resize the screen until the navBar collapses like in the following image:
  
• Click on the hamburguer button.

Bug: Duplicate entries for qiskit textbook / qiskit.org/learn

Steps to reproduce the problem

Go to https://qiskit.org/ and click on "Documentation" to open the mega drop down menu

What is the current behavior?

There is already "Learn" in the top level item of the top menu. We don't need to have another entry of "Qiskit Textbook" in the drop down menu under "Help and Learning". I am not sure whether this was a conscious decision in #140

What is the expected behavior?

1. Remove "Qiskit Textbook" from "Help and Learning" column.
2. Rename "Help and Learning" column to "Get Help".

Screenshots

No response

Device

No response

OS

No response

Browser

No response

Additional information

No response

Multiple "Overview" buttons on top menu causes confusion for documentation users

In the qiskit.org top menu there are 2 instances of the word "Overview". One at the top level and one inside the documentation dropdown. This was recently raised by a Qiskit maintainer as confusing for documentation users because when users go to the documentation page there is an overview page and it isn't clear that the top menu "Overview" redirects back to the qiskit.org homepage instead of the documentation overview page. I suggest renaming the top level "Overview" to "Home" as a way to prevent this confusion.

As a Qiskit Developer, I need the UI shell component available via a custom CDN so that I can integrate it into my HTML project

Background:

The unified top menu has been released on all the pages within Qiskit.org other than the documentation, the below will address the final blocker we have preventing this from getting released to the documentation pages.

Acceptance Criteria:

1. Need to set up a CDN in IBM cloud -> link to tutorial
2. Need to make UI shell component available via the CDN
3. Set up automatic deployment when to the CDN when changes are made in the web components (so that users of the component via the CDN can get the latest versions)
4. Document to users how to use the component via the CDN

Related open issues:

• carbon-design-system/carbon-for-ibm-dotcom#6361

Additional context

We are unable to use the existing third party CDN because it is incompatible with certain dependencies in the carbon component, this is a blocker for this open issue: Qiskit/qiskit_sphinx_theme#64

In order to have the unified navbar on the documentation page, this blocker needs to be addressed. Additionally, if we want to be able to use web components within the docs in the future, we will need components available via the CDN.

cc @javabster @abdonrd

`MegaMenuDropdown` styling

Steps to reproduce the problem

1. view the web component implementation in the Storybook or in this Qiskit.org branch preview
2. notice the different sizes, compared to that of the current qiskit.org/textbook-beta megaMenuDropdown component

What is the current behavior?

The behavior is fine, but the styling is incorrect.

• the new web component has more height
• the new web component has too little left and right padding

What is the expected behavior?

According to our design team, the new web component should preserve the styles from the currently implemented megaMenuDropdown on qiskit.org/textbook-beta

Screenshots

MegaMenuDropdown in header



MegaMenuDropdown in nav

Find new approach to handle releases

Feature description

Currently, we're using the changesets workflow to help w/ our releases. This made sense when we were aiming to build a monorepo; however, since we're no longer going for a multi-package repo, we should switch to a different approach.

Also, there's something broken about the current way in which we're handling version releases; and this bug in our process has been requiring someone w/ admin privileges, to have to manually Squash and merge PRs.

__
Here are a few automated release packages that we can look into:

• https://github.com/semantic-release/semantic-release
• https://github.com/release-it/release-it
• https://github.com/googleapis/release-please

Additional context

No response

simple question

this project is only for qiskit- related web content, and not visual/interactive components for the qiskit itself, correct?

Fix the changeset warning

From: https://github.com/Qiskit/web-components/actions/runs/1689030873

The workflow file using changesets/action is currently using @master as the version. This branch has been frozen and deprecated. Please update your workflow to either use @v1 or a specific commit SHA that is tagged.

[Navbar UI] Unnecessary line in navbar dropdown

The elements of the dropdown in the navbar have an unnecessary extra line that shouldn't be there:

[UI Shell] - need to differentiate Overview CTA from Documentation > Overview CTA

Steps to reproduce the problem

On qiskit.org make sure to have the segment extension. First click the top navigation Overview link. Then click Documentation and click Overview from the dropdown. See in segment that both events have the same CTA

What is the current behavior?

Currently, we have the segment click event CTA value as the navbar link label. This is an issue specifically for the Overview in the top-level nav and the Documentation > Overview in the documentation dropdown

What is the expected behavior?

Should be able to differentiate different each link clicked in ui-shell

Screenshots

Device

No response

OS

No response

Browser

No response

Additional information

Consider adding parent menu label as prefix for all nested links

[Navbar] The Qiskit logo does not appear in Safari

Steps to reproduce the problem

Just open the Navbar story:

https://qiskit.github.io/web-components/?path=/story/navbar--default

What is the current behavior?

The Qiskit logo does not appear in Safari:

https://qiskit.github.io/web-components/?path=/story/navbar--default

What is the expected behavior?

The Qiskit logo appear in Safari.

Additional information

Extracted from: https://github.com/Qiskit/saiba/pull/53

Update repository user permissions

The repository user permissions are outdated and need to be adjusted.

The build step is not working as expected

Whith this PR we start to export an experimental bundled version of the UI Shell component:

• #177

But as we run the tsc command two times:

web-components/package.json

Line 27 in 32469a6

"prepack": "npm run build && npm run build:ui-shell-bundle",

web-components/package.json

Lines 17 to 18 in 32469a6

	"build": "tsc && rollup --config rollup.config.js",
	"build:ui-shell-bundle": "tsc && rollup --config rollup-ui-shell-bundle.config.js",

We override the first build and break the components:

• https://unpkg.com/browse/@qiskit/[email protected]/components/banner/index.js
• https://unpkg.com/browse/@qiskit/[email protected]/components/banner/index.js

Note that the v0.10.1 has the import styles from './index.scss' instead of the CSS.

[UI-Shell] update navigation items

Feature description

• related to this issue in the Qiskit.org repo
  • specifically this comment
• also related to #160

Main menu updates:

• The link to the Providers page will be near the Documentation link, on the right side
• The links to Providers and Core will be removed from the Documentation drop-down menu. Not yet

Additional context

Here we need to decide if the block will continue having the size of the screen or if we want that block to adjust to the content on the submenu. Update: We don't need to remove the providers and core section from the menu, so the size will remain the same

Note: possibly related is this issue from @HuangJunye, regarding the width and usability of the UI Shell Documentation dropdown

Create a pull request template

This is a follow-up on Qiskit/qiskit.org#2456.

As part of our attempt to improve the health of our code review process, we can create a pull request template to try and:

• warranty that the pull request author will check certain code quality criteria,
• provide the code reviewer(s) with helpful information for the review, and
• better document changes for the future, when looking back trying to understand something.