woocommerce/woocommerce-admin

(Deprecated) This plugin has been merged to woocommerce/woocommerce

WooCommerce Admin

This is a feature plugin for a modern, javascript-driven WooCommerce Admin experience.

Prerequisites

WordPress 5.6 or greater and WooCommerce 5.7.0 or greater should be installed prior to activating the WooCommerce Admin feature plugin.

For better debugging, it's also recommended you add define( 'SCRIPT_DEBUG', true ); to your wp-config. This will load the unminified version of all libraries, and specifically the development build of React.

Development

After cloning the repo, install dependencies:

• pnpm install to install JavaScript dependencies.
• composer install to gather PHP dependencies.

Now you can build the files using one of these commands:

• pnpm run build : Build a production version
• pnpm run dev : Build a development version
• pnpm start : Build a development version, watch files for changes
• pnpm run build:release : Build a WordPress plugin ZIP file (woocommerce-admin.zip will be created in the repository root)
• DRY_RUN=1 pnpm run build:release : Builds a Wordpress plugin ZIP without pushing it to Github and creating a release.

For more helper scripts see here

For some debugging tools/help see here

For local development setup using Docker see here

Typescript

The npm run ts:check command will check your TypeScript files for errors, and has been added to .vscode/tasks.json. Running this task in vscode will highlight the errors in your editor file navigator.

If you allow the npm run ts:check:watch command to run automatically as configured, it will run in the background and pick up any errors as you save the files. Note: Even if you don't run this task, the IDE uses its language server to pick up type errors in files that are open. This is only necessary for picking up errors across the entire repository even when they haven't been opened in the IDE.

Testing

End-to-end tests

Tests live in ./tests/e2e. An existing build is required prior running, please refer to the section above for steps. E2E tests use the @woocommerce/e2e-environment package which hosts a Docker container for testing, by default the container can be accessed at http://localhost:8084

All the commands from @woocommerce/e2e-environment can be run through pnpm exec.

# Set up the e2e environment
pnpm i
pnpm exec wc-e2e docker:up

Run tests using:

pnpm exec wc-e2e test:e2e-dev

or in headless mode:

pnpm exec wc-e2e test:e2e

Run a single test by adding the path to the file name:

pnpm exec wc-e2e test:e2e-dev tests/e2e/specs/activate-and-setup/complete-onboarding-wizard.test.ts

Documentation

There is documentation in 2 forms available in the repo. A static set of documentation supported by docsify and also a Storybook containing component documentation for @woocommerce/components.

To view the docsify docs locally you can do:

pnpm install
cd docs
pnpm exec docsify serve

When deployed the docsify docs also host an embedded version of the storybook docs. To generate that and test it locally in docsify you'll need to run:

pnpm install
pnpm run docs
cd docs
pnpm exec docsify serve

Then navigate to Components from the left hand menu in the docs.

If you would like to view the storybook docs hosted standalone, then you can run:

pnpm install
pnpm run storybook

If you would like to view the storybook docs in right-to-left styling, you can run this instead:

pnpm install
pnpm run storybook-rtl

Common Issues

If you're encountering any issue setting things up, chances are we have been there too. Please have a look at our wiki for a list of common problems.

Privacy

If you have enabled WooCommerce usage tracking ( option woocommerce_allow_tracking ) then, in addition to the tracking described in https://woocommerce.com/usage-tracking/, this plugin also sends information about the actions that site administrators perform to Automattic - see https://automattic.com/privacy/#information-we-collect-automatically for more information.

Contributing

There are many ways to contribute – reporting bugs, adding translations, feature suggestions and fixing bugs. For full details, please see CONTRIBUTING.md

woocommerce-admin's Issues

Component: Agenda Accordion

This issue covers creation of a new component(s) that can be used to render the accordion section seen in the Agenda block:

We may consider using @components/panel-body for this task, though with the custom counter in the header area, it might need to be a custom component.

Also <FoldableCard /> from Calypso is quite nice.

This issue covers creation of the Clickable header region, which will expand/display the child region. This does not cover the rendering of child items/content.

Props
Some props the component should likely support:

• title string
• isOpen bool
• count int

Timeline: Update Tabs

Please note: the final designs are still in progress for this

Currently the tabs in the Timeline Sidebar look like:

And the latest designs now has the tabs appearing in the header component:

For this task we should implement the following changes:

• Update/Add new tabs
• Update styling of tabs / components to reflect the new design
• Implement active tab states
• Implement toggling of tabs open/close by clicking on the same tab that is open. I.E. if 'Orders' are open, clicking on 'Orders' again will close the sidebar.

Component: Segmented Control

This smaller component will be needed to build the DatePicker:

In Calypso there is a SegmenedControl component we could use for prior art - but there doesn't seem to be a similar component we can pull in from Gutenberg.

Rename js/src?

Right now, all of the app code (including .scss files) are in js/src.

Should we rename this directory to just src, or app or client? since 1) It contains JS and styles and everything that makes up the app and 2) It doesn't seem like we will have another directory under js/?

Seems better to do so now before we continue adding more :)

cc @ryelle

Component: Performance Indicators Header / Selector

Based upon the latest designs in p6riRB-3en-p2 - we need to update the current "Store Performance" block. This might be best tackled once #82 lands so we can actually show the tiles, and have the toggle feature working with the new Tile component.

Current Look

Performance Indicators Block

Selector
As Jay commented below, the ellipsis menu will expose a selector which allows users to toggle which tiles to display:

Tasks

• Change header area styling: smaller text, title
• Adjust Ellipsis menu styling: purple toggles, selection label/prompt, adjust options shown

WordPress Notifications Panel

Previously in #36, we hide all WP notifications from displaying on dashboard pages. To still make these available to users, we will be implementing a WordPress icon button in the header area. On hover, this icon will show how many notices, and clicking will show a list of notices.

Gutenberg has some components (Popover, Dropdown) that should help build this out.

See p6riRB-3bd-p2 for designs.

Add SASS Colors & Breakpoints

While working on the header component, I realized we should create SASS variables for common colors (grays, WP, Woo colors, etc) and mixins for breakpoints so that we can start using them early on.

See https://github.com/Automattic/wp-calypso/blob/3c19b760a5a2ed5d35e76030f2bad40ebd04553b/assets/stylesheets/shared/mixins/_breakpoints.scss for breakpoints.

Tabs: Focused state indication

Tabs in the sidebar as well as datepicker should have styles indicating they have focus. These styles should be outlined in the hifi designs

Component: Button

Currently the only design I'm seeing that has a need for a button is the Agenda Item - but guessing we will have use for a base button component frequently in the project.

I'm wondering if we can use the gutenberg button for this project - but if we want to track click usage, not certain if that will work.

CSS Layout: Consistent padding

Our code base is gathering inconsistent padding as elements take shape. Some examples:

padding: 12px;
padding: 8px 16px 8px 16px;
padding-bottom: 10px;
padding: 2em;

Now is a good time to set some standard rules for padding so elements and their contents line up without developers needing to think about it too much.

Additionally, there are benefits to using relative units such as em or rem so that padding can reflect changes in font-sizes made to the entire document or component.

Some info here, https://webdesign.tutsplus.com/tutorials/comprehensive-guide-when-to-use-em-vs-rem--cms-23984

Bug: Masterbar/Notifcation Panel Conflicts

Steps to Reproduce:

• Install woo-dash on a site that has Jetpack installed and the masterbar feature enabled
• Visit either the WC Dash page, or Analytics page
• Click on the notifications bell
• Note ( ) the panel is not displayed correctly

Originally spotted by @LevinMedia. Also on smaller viewports there is no padding on the right side of the main dashboard content area.

CSS classnames Standards

The WooCommerce style guide points to the WordPress core css standards as the authoritative source for css guidelines.

Prior to us creating many components I wanted to verify how we want to structure component css classnames, and modifier class names. Should we conform to the standards in wp-calypso or ...?

/cc @jameskoster, @kellychoffman, @LevinMedia, @josemarques

Task
Given the choice to stick to WP core standards with a Gutenberg stance, perhaps we should add a bit of info to the README around coding standards.

i18n: numberFormat

Something similar to i18n-calypso's numberFormat will be required to format numbers.

Gutenberg's wp.i18n does not contain number formatting

For context, JetPack uses i18n-calypso:

https://github.com/Automattic/jetpack/blob/f97d8f3b8578ce2ce4edc041b1f532dca406b3fe/_inc/client/at-a-glance/stats/index.jsx#L15

Try/Question: React Virtualized for Tables and Feeds

Design Background: Via p6riRB-36R-p2

Tabular data in Analytics is going to be an often used design pattern in the project, and there will also be a feed area to display notifications that will need to have an infinite scroll type feature as well.

In Calypso we have used react-virtualized to display scrolling feeds of large data sets. The library also has some rich support for tables which we could absolutely leverage many features of like a static header row which headers can be clicked to sort larger data sets:

The table layout below is created with flexboxes. This allows it to have a fixed header and scrollable body content. It also makes use of Grid for windowing table content so that large lists are rendered efficiently

At first glance this seems like it could be quite useful in this project - but are there other options out there? I have worked with the library a bit and it was challenging at times, but the features are quite nice.

Analytics: Create npm package from Calypso Store D3 Components

/hat tip to @greenafrican for this idea

Since a large amount of time and resources have been invested already in creating some fantastic visualization components for Store Stats on WordPress.com - this task involves extracting those components into a stand-alone module that can be required by both wp-calypso and woo-dash.

This will kick-start the work around Analytics within this project, and in-turn, Calypso will also benefit from any new visualization development that is performed here.

Create header navigation component

Based off the initial lo-fi design concepts, this issue involves creation of a new Header/Breadcrumb component, which is quite similar to the <ActionHeader /> in Store:

Component: Agenda Item

Requires: #28, #49

This issue covers creation of a component for the individual Agenda Items that are exposed when you toggle open an <AgendaAccordion />

Thinking the "body" section of the agenda item could just be the child components, but will leave that up to whomever grabs this issue. The other prop that seems to make sense to me is an action, and action label - which seems a function could handle most use cases for the action itself.

Handle Admin Notices

A full solution for handling admin notices is still being explored by the designers (see p6riRB-37z-p2 #comment-3680).

In the meantime, I think we can partially handle this by hiding them on our dash pages. We can keep this issue open until a design is made and implemented.

Right now, we can end up with this happening:

Build Process: CSS reset is duplicated in the built CSS

The mixins & color variables are OK to be imported multiple times, but the reset itself is included with each SCSS partial.

Try searching the built style.css file for .woocommerce-page #wpcontent, you can see it appears 4 times. We could import it into one of the SCSS partials, instead of via the webpack config.

Implement Ellipsis Menu Component

A common UI feature in the dashboard is the ellipsis menu in the upper right corner of blocks:

There is some prior art to work with which we may be able to leverage here:

@components\popover in gutenberg

And Calypso has the <EllipsisMenu /> component , which I believe utilizes popover too. In my quick testing, it seems the Ellipsis menu can be activated by tabbing/entering, but i could not arrow down into the menu items - so there is likely some a11y with that implementation.

Store Performance Header Updates

Based upon the latest designs in p6riRB-3aN-p2 - the Performance block header needs a few revisions:

• Remove ellipsis menu from header
• Link Block title to Analytics Overview page, with external gridicon
• Implement a segmented control for period (today, this week, this month) - previously #69

Dashboard: Create base Block component

From the lo-fi design, we can see the basics of the <Block /> component that will be used to build out the dashboard:

Features / Props

• Title attribute is consistent across all block designs
• Elipsis Menu is shown on the right side of the header area, for this issue we can just have a placeholder for this.
• Some blocks will also have secondary actions immediately to the left of the elipsis menu. These items wrap to below the title on small viewports ( see screen grab above ).
• Component should also support a custom className prop for further css customizations
• In smaller viewports, the block body will horizontally overflow/scroll ( see chart in above example ).

Component: Performance Tile

Many blocks in the Dashboard contain a "Performance Tile"... and since the Tiles are comprised of a variety of components - this issue will serve as a parent issue for child tasks.

This design is greatly simplified from the prior iteration, and the tile now encompasses some very minimal props:

label - a string that labels the statistic
statistic - the large statistic shown
trend - the percentage trend + or -

Analytics: Pagination Component

The tabular data shown on all new reports includes the ability to navigate between pages:

This component should include the following features:

• Show the current page being viewed out of total pages
• The ability to jump to a specific page number
• The ability to move forwards and backwards in pages via < > arrows
• The ability to change the number of rows shown on a page
• The ability to inform a parent component that controls the data represented on the page of these changes via a callback function, or perhaps a ui state

@LevinMedia what were the presets you were considering for the per-page drop down?

Update base layout

Based off the i1 lo-fi design, we can begin to start creating some of the layout containers needed for both the dashboard and the analytics sections of the project:

For both dash and analytics, it seems the above represents the base containers we could use. I'm not tied to the names by any stretch, but borrowed some from Calypso.

Dashboard: Create layout regions

Based upon the early lo-fi designs, we can proceed to implement some layout regions for the dashboard:

Once again I'm not tied to the namings here, nor nesting of notices within primary, but wanted to highlight the three regions in the dashboard.

Worth noting, on smaller viewports the <Secondary /> region will not be displayed, but can be toggled into view by clicking the clock icon in the header region:

/cc @jameskoster, @josemarques, @LevinMedia, @kellychoffman for any input on screen dimensions for these regions. Also curious if we have thought about breakpoints yet for toggling the display of the timeline feature.

CI Needs?

I wanted to open an issue to gather thoughts around implementing CI on this project. Since we will very likely have both PHP and JS test suites, it might be nice to have both run against all PRs - akin to what we have in Calypso. But curious to hear other thoughts on the topic.

Analytics: Tabular Data Component

Designs: inVision
Master Thread: p6riRB-3lZ-p2

There are two types of tabular data: standard, and filterable/comparable.

Filterable/Comparable tabular data includes the ability to search and filter rows directly in the component. Additionally, each row can be marked with a checkbox to quickly create a comparison (when two or more rows are checked)

• Update style of existing table component
• Add table header component #94
• Add table summary component
• Create a "wrapper" component for all of the above

(issue updated to a "master" issue, to reflect new designs, by @ryelle)

Style Guide: Create a template for component README

If all components have READMEs with the same layout and style, it will make finding information more useful.

Analytics: Create Menu Item and Page for WC Analytics

The new Analytics/Stats system is going to be accessed via its own distinct sidebar menu item within wp-admin:

Early Design Concept

This task involves registering an additional sidebar menu item for the Analytics page, which upon visiting will render a ( for now ) empty page which will eventually house the new ✨ reports.

Component: Light Date Range Picker

p6riRB-3aN-p2 highlights a lighter date ranger picker for use on the main dashboard in the store performance card. This is different from the more advanced Analytics picker seen at #59.

This picker is still a WIP, but will be a more basic segmented date range control:

Try: @components/slot-fill

Design Background: p6riRB-35x-p2

Based off some of the early design mocks, discussions around them, and our primary goal of the Dashboard being built with Extensibility First - one of the key features of the project will be the ability for internal core devs, and extension developers to build custom blocks, and for users to add them to the dashboard.

While the designs are still being finalized, we can still use an early mock-up to see how "slots" to house custom blocks could potentially be utilized:

Goals
For this Try Issue, the goal is to explore the slot-fill concept leveraging the @compontents/slot-fill component created for Gutenberg.

Ideally to vet this idea it would be nice to see the basic woo-dash page have:

• Two slot-fill target regions ( maybe Main and sidebar )
• Example components that target the slots and render content into them

Discussion
While these items are out of scope of the try branch I wanted to capture some other questions I have been pondering around this topic:

• Do we need to support priority of insertion into fill areas?
• There has been chatter around customization of the dashboard, could users re-arrange blocks in fill areas to customize?

Add js testing framework

A way to run unit tests on client side code will be nice

Component: ActivtyCard

The activity timeline's main block design is referred to as an Activity Card. These do share many similar patterns to the <Card /> that has already been created - so perhaps we can extend that base component, or modify it to handle the additional props - or create a stand-alone component.

Designs: Activity Template

Remove references to Foxhound from .eslintrc

I copied the eslint config from a personal project, and accidentally left references to globals used there. Not a problem for us, but we should get rid of them. Just making an issue so I don't forget this after our team meeting 🙂

Try: Extensions API

Related to: #3, and much of the description copied from there.

Design Background: p6riRB-35x-p2

Based off some of the early design mocks, discussions around them, and our primary goal of the Dashboard being built with Extensibility First - one of the key features of the project will be the ability for internal core devs, and extension developers to build custom blocks, and for users to add them to the dashboard.

While the designs are still being finalized, we can still use an early mock-up to see how "slots" to house custom blocks could potentially be utilized:

Goals
For this Try Issue, the goal is to further explore the Extensions API concept ( p90Yrv-Ae-p2 ) that @justinshreve presented at our meetup.

Ideally to vet this idea it would be nice to see the basic woo-dash page have:

• Two slot-fill target regions ( maybe Main and sidebar )
• Example blocks that are registered via PHP, and subsequently rendered into slots

Discussion
While these items are out of scope of the try branch I wanted to capture some other questions I have been pondering around this topic:

• Do we need to support priority of insertion into fill areas?
• There has been chatter around customization of the dashboard, could users re-arrange blocks in fill areas to customize?

Component: Timeline Seperator

In the timeline, there is a small component that breaks out the cards by day/time period. This enhancement is to create a new component for the _Timeline Separator

Timeline: Implement "Sticky" Store Activity Tabs

This was discussed during our woo-dash hangout this week - in-lieu of having the ability to set a default tab in the sidebar, the notion is to remember which tab the user interacted with last, and have it persist as the default tab on subsequent page views.

So for example if I last looked at the 'Orders' tab in the sidebar, the next time I visit the dashboard, or open the sidebar panel on another Woo page, the 'Orders' tab will be selected.

---- update 2018-06-11 -----

Based off the new designs and discussion in p6riRB-3en-p2 the Activity Tabs should now stay persisted while using WooCommerce ( new and old screens ). This is somewhat blocked by #96, but ultimately:

• If a user opens the 'Orders' tab, and subsequently clicks on 'Products' ( legacy wp-admin screen ) in the wp-admin sidebar, the 'Orders' tab will be open/expanded on the Product listing page.
• For this to work properly, perhaps we need to look at persisting the last open tab as a user option? This would make the tabs sticky between visits/log-in/log-out too.

Component: Date Picker Display / Launcher

Child task of #59

The Date Picker will be shown in a variety of situations ( ref the parent task above and linked p2 post for more design background there ), but one recurring use case is it being launched via a drop/down popover selector. For example, this is how it would appear when launched from the Store Performance block:

Closed

Open

Based off the design, it seems the launcher/display needs to be aware of possible props:

• isOpen <Bool> Is the date picker currently open/shown
• label <String/> The active date range, summarized for the label shown

And it seems like it should be aware of the start/end date of both ranges ( the range being shown and the one being compared against ). Though not 💯 certain on that.

Design Needs
I did note this in a prior p2 conversation that thus far most of the designs have always shown "Today vs Yesterday" in the launcher label. I think we need to have some design mocks done for other things like custom date ranges, or "This Quarter vs Last Quarter" - strings that will overflow the minimal space we have to display text. /cc @LevinMedia @jameskoster

Documentation: Add a README to use-filters, clean up plugin

Add a readme to the use-filters higher order component, so we can remove the demo from the plugin itself.

@timmyc Do we know yet what things we might want to be filterable? Or should we maybe pull this code too, and put it on the "vLater" list with the other extensibility work?

Update wp-admin sidebar navigation

Last week in the woo-dash chat, we decided to make some updates to the wp-admin navigation:

• Remove WC Dashboard as a separate item.
• Update the WooCommerce link to point to the new dashboard, and add a new sub-menu item.
• Rename WooAnalytics to Analytics and move below WooCommerce.

Component: Sparkline

Child task of #82

UPDATE
The sparkline component is no longer being shown in the latest designs for dashboard blocks. As such I'm going to remove this from the backlog for now - and lets not work on this for the time-being.

---

Based upon the latest designs in p6riRB-3aN-p2 - each performance tile will include a Sparkline that will display the trend of data for the given stat:

Ideally it would be nice to leverage the existing Sparkline component from calypso, and I'm going to chat with @psealock around some ideas of how we can best bring over the prior art to use here.

Component: Preset Group

Child task of #59

The default view of the Date Picker presents a grouping of date range presets for the user to select from. The following lo-fi screen grab shows two uses of the "Preset Groups" on the date picker:

Based off the designs, it seems this component could likely have the following props:

• options <Array> an array of options perhaps expressed as an object { label: ..., value: ... }
• onChange <Function> a handler that is called when the selection is changed
• selected a way of denoting which option is currently selected, or would this be better on the option itself in the array?

Anyhow, implementation details are up for grabs ( as always ), just spitballing a few ideas 😄

Component Library

One feature I enjoy in calypso is the ability to browse blocks from devdocs. Should we consider building our own component library with documentation/examples as we build out components for the Dashboard and Analytics?

This could serve as internal documentation for us, and eventually be a fantastic resource for 3PD who want to use design patterns from Dash/Analytics in their own extensions.

Component: Activity Tabs

Blocked by #20

This issue involves creation of components that will comprise the Store Activity tabs that are shown in the Sidebar of the dashboard, and will eventually be rendered in other Woo views by clicking on the timeline icon in the navigation header.

Goals of this issue are to create components that:

• Render the 3 tabs: Insights, Orders, Reviews
• Logic to Toggle active state of tabs
• Support an unread count for tabs, likely a <Count /> component would be nice to create as part of this

Activity: Create Order Activity Feed

Utilizing the ActivityCard component shipped in #86 - this feature involves populating the "Orders" tab in the sidebar with orders that need to be fulfilled.

This list should contain all orders that are "Pending".

Additional Design Input Needed

• What are the action links that will be shown for pending orders?

/cc @josemarques

NPM Dependency Watcher

Inspired by p4TIVU-8Vy-p2 - let's look into some of the similar solutions being explored for Calypso to ensure our npm dependencies stay current.

https://greenkeeper.io/

Create Tracks Client Wrappers

Collecting usage data of the new Analytics and Dashboard projects will be key to determine which features our users are interacting with most frequently. During the last woo-dash hangout we discussed the notion of using the Jetpack Tracks Clients to implement tracks within dash/analytics.

Goals

• Determine if it is feasible to utilize the existing Tracks clients that are available in Jetpack. I.E. can we have our own tracks namespace for the project yet still use the JP clients?
• Since not all users of the feature plugin will have Jetpack installed / activated - look into creating a wrapper of the JP classes, or similar logic that can be called within PHP and JS code to record tracks events

Component: Date Picker

The DatePicker is one of the more complex components that has been displayed in the designs thus far. The best way to get familiar with the concept is to ready the original thread by @LevinMedia and watch the screen cast he provides in p6riRB-38x-p2

This component will be present on all new Analytics pages as setting date range on all reports is a primary function for all reports. Additionally the Date Picker will be utilized in the Store Performance block.

This issue will act as a parent issue for all related tasks to the Date Picker. Since there are a number of components that comprise the feature - I feel it is best to break it up into child tasks to allow multiple people to work on it simultaneously - and prevent the dreaded long-running large pull requests from happening 😄

Child Issues

• #58 Component: Segmented Control
• #60 Discovery: Custom Calendar Range Pickers
• #61 Component: Preset Group
• #62 Component: Date Picker Display / Launcher

Lo Fi Designs

Discovery: Custom Calendar Range Pickers

Child Issue of #59

The Date Picker has two modes, one allows users to select from "preset" date ranges ( i.e. Today vs Yesterday ), but the designs also call for the ability to select a custom date range.

@LevinMedia noted in his initial design post that we should consider exploring the date range selector created by the fine folks at AirBnB - react-dates

Another pony in the race is date-picker from Calypso. This option currently only supports selection of a single date, not a range ( I think ) and it is using https://github.com/gpbl/react-day-picker behind the scenes.

Likewise, Gutenberg uses react-day-picker for the calendar to select a post publish date.

And of course there is the roll your own option. But that might be a tad bit crazy.

For this task, I would like to see the above two options vetted for our needs in the Date Picker, so specifically we should evaluate:

• Can the option support selection of a date range? If not, what is the estimated level of effort to include that.
• Does the option of good a11y? Can one navigate the calendars via keyboard?

At first glance it appears react-dates might be the best option for us, but the goal of this task is to verify that assumption, or see if trying to build on top of what is used thus far in Gutenberg ( react-day-picker ) could also suit our needs.