foxy / foxy-elements Goto Github PK

The reports collection has recently been added, documented here: https://api.foxycart.com/rels/reports

The resources are fairly bare, so the collection page should probably use a full-width table element. There's no real need for a card display for an individual report, but the one unique thing about report resources is the _links["fx:download_url"] is short lived (currently 10 minutes), so there's a chance the link won't work when clicked. To avoid this, I propose the following:

1. Output a collection table that includes a download link. This link should not point to the fx:download_url. (Alternately, instead of a download column, it could be a status column, where a status of "ready" outputs the download link.)
2. On click of the download link, a GET to the specific resource should be made, and the fresh _links["fx:download_url"] value should be downloaded at that time.

This ensure the links will always work, even if the user doesn't click on them until >10min after pageload.

PLACEHOLDER TICKET. More work on the ticket is needed before work can begin.

Allow foxy-items-form to reflect current cart contents

If FC.json.items is populated, and perhaps if foxy-items-form has a reflect-cart attribute set (language tbd), it should populate with the current cart. That'd allow this component to be used in a huge number of additional circumstances.

Additionally, quantity changes at that point should actually update the cart.

This may also require optionally hide/display the frequency modification and add-to-cart button, as it might not make sense in that context.

Gift card codes can be attached to a customer either via a customer_id (integer) or the ._links["fx:customer"].href (URL) value on the gift card code resource.

We'll want to allow this to be handled from the elements. For now, if we can accept the ID, the email (which we can get the ID from, as there'll only ever be 1 non-guest customer per email), or the full URL (back-end API URL, though we could conceivably pull the ID from the new admin URL if it'd make sense), that'd be good.

Just a small little issue one of our users spotted - the logout button on the portal doesn't use the pointer cursor when you hover over it. The edit button next to it does, but not the logout button.

Password managers have trouble with the shadow DOM and web components:

• lit-element
• Vaadin apparently has fixed this (per comments on the lit-elements ticket)
• Polymer
• Firefox ticket

The goal would be for password managers (1password, LastPass, Dashlane, Chrome/Firefox/Safari/Edge built-in options) to…

1. Prompt to save on submission
2. Prompt (or allow) autocompletion

The best approach is TBD, but options are probably limited.

When working with the items property of the foxy-items-form, my expectation would be that modifications of an items object would update foxy-items-form. That's not what happens. Example:

const foxyItemsForm = document.querySelector("foxy-items-form");
foxyItemsForm.items = [{name: "Foo", price: 19.99, description: "Fancy stuff goes here!", code: "abc123", image: "https://placekitten.com/300/300"}];
foxyItemsForm.items[0].quantity = 1;
// I'd expect the display to update, but it doesn't.
console.log(foxyItemsForm.items[0].quantity); // Expect 1. Returns 0.

If fx:item's image property is empty or pointing to an inexistent file, the form needs to hide the default browser ui (rectangle with broken image icon) and show a placeholder image instead.

The Foxy API doesn't currently have any ability to retrieve all the individual downloadable products a customer has purchased in the past, but once that is possible via the API, the customer portal should include a section listing previously purchased downloadable files.

We need to add a read-only list next to the Applied Taxes section showing all applied gift card codes. This may require developing a new card element.

Update existing elements and build new ones with cmd/ctrl+enter shortcut to trigger form submission. Keep submit-on-enter behaviour alongside this approach for non-destructive actions.

Some types of data in the admin are very likely to be copied out by store admins and CSRs, and pasted elsewhere. For instance:

• Coupon codes may be long and random strings that need to be entered into emails. Coupon UI.
• Same with gift card codes. Gift card UI.
• Customer email addresses are often needed for copy/pasting into an email client or elsewhere. Customer UI and Transaction UI.
• Customer addresses may be copied out for pasting into other systems. Customer UI and Transaction UI.

Let's add the standard "copy to clipboard" icon small and subtle for these above types of data. Will make using the admin much more pleasant for certain use cases, and is a nice touch. (Nice on desktop but very helpful on mobile.)

We recently landed on a default z-index of 1000 for the foxy-dialog-window element, which is a decent default. We've already been foiled though, as Bootstrap uses a default for their varying elements between 1000 and 1080: https://getbootstrap.com/docs/5.0/layout/z-index/.

Considering the popularity of Bootstrap, we should probably use a default that's higher than theirs. Obviously we'll always have something higher, and people can customise with CSS, but at least being higher than Bootstrap makes sense to me.

Cents do not show in amount options: https://d.pr/i/Zc9uD9

Possibly related, when you choose a pre-defined amount, "Other" is selected. Takes a couple of clicks to get a pre-defined amount selected.

The gift_card resource now accepts a current_balance parameter on gift card code creation:
https://api.foxycart.com/rels/gift_card

Let's get that added to the element to make things easier for folks creating multiple gift card codes with starting balances.

Add user-submitted French Translation

If you log in to the customer portal using a temporary password, we should prompt the user to update their password straight away. The temporary passwords are designed for single-use access, so once they use it to log in, their next step should be to set a new password.

This may also necessitate an update to the API to identify in the login response for whether a password reset prompt should be required. The foxy-sign-in-form is built to handle a forced new password if a login response of { "code": "new_password_required" } is returned.

User reports that when using a radio list of values plus the other option, selecting the Other option and typing in a value that starts to match a value in the list (in this example, attempting to type in $500), the keystrokes cause $50 to automatically be selected, and the donor can't type in the additional characters for the correct amount.

This appears to be an issue in the default widget, as I was able to reproduce it without any modifications to the widget.

Some payment method resources may have null in the cc_type, which doesn't appear to be accounted for in this version. As a result, the payment method card fails to render.

Let's add a customer card (like on the transactions page) to be able to see a customer's info from the subscription detail page, and/or to allow clicking through to open the customer directly. Not opposed to displaying the customer ID as well, if it makes sense. (Applies to the transaction view as well.)

Related to #86 and gift card provisioning (app#5993).

For normal functionality, as well as to support gift card auto-provisioning (ie. being able to sell gift cards, provision them, and notify a gift recipient), we'll need UI for item_categories.

Notes:

• The discount_ parameters should probably reuse UI from the coupon (and gift card) elements (currently still in beta).
• The _email templates will include gift_recipient_ params (in addition to admin_ and customer_). Unlike the current admin, the actual template UI (subject, html template, text template, etc.) should not be on this page. Instead, each email template should present a selection of existing email templates to associate. (To create new templates will be done via #86.)

It looks like we're using the customer's default shipping address for the shipping address on the individual transaction display. Instead, this should be the address from the individual shipment (fx:shipments), as the shipping address on a transaction could be different than the customers default shipping address (because it changed since, or because it is a multiship order).

This was noticed because a customer had edited the address on a transaction using the legacy administration, which updated the shipment address, but not the customers default address. In the new admin, it's still showing the original address from the customer, and not the updated address from the shipment.

We've had requests to put the password reset form on its own standalone page, so we should make the password reset form a public element, to allow for easier embedding.

Some systems (like Wix; really just Wix) only allow custom HTML to be embedded in iframes, which results in the donation form loading the Foxy checkout within the same iframe.

We need to allow the donation form to target the _parent or _top, to allow it to work in Wix.

On the foxy-item-form (in the context of editing a subscription, but this applies for all instances), the "Item Options" section should be moved to the 2nd position, below "Subscription".

If possible to go a little more advanced… 
It'd be really slick to sort the resources (or "pseudo" resources; the subscription, line item discounts, and "cart" for instance aren't actually separate resources) that are non-empty above, and dim out (and/or hide by default) all the resources that don't exist. For instance, the subscription block is pointless noise if the item has no sub params.

Currently, we use action="https://${this.store}.foxycart.com/cart" to render the store's domain — we need to change this to account for the use of a subdomain. We could potentially just require the entire domain (foxycart.com or otherwise) in the store option, or maybe there's a better way to do it.

We'll need to update the documentation as well to make sure it's clear.

The MFA input should be focused whenever it appears. So if the email + password is submitted, and the foxy-sign-in-form updates to display the MFA input, it should be focused so a user can enter the OTP without any additional mouse or keyboard work.

Accessing individual shipping options in admin crashes browser. User reported this issue and we reproduced in Firefox, Chrome, and Safari. To reproduce, log into admin and select Settings->Shipping. Selecting Custom Shipping Code seems to reproduce it always for me, but if I select a few different options one after the other, it may freeze up as well.

The doc needs information on the JS and basic html on setting up the donation widget.

A user noticed that some elements in our docs aren't displaying correctly, for example the sign in element:

Related to #11, possibly d2fd62c

Currently, when working with subscription items, every item gets the sub_modify=replace and sub_restart=auto options added, prefixed with the digit. These params need to be passed to /cart just once, without any prefixes. So currently if you inspect the POST in the dev tools, you'll see something like this:

10:name: Fancy Widget
10:code: 1003
10:price: 27.94
10:image: https://foo.tld/bar.png
10:quantity: 1
10:sub_frequency: 30d
10:sub_modify: replace
10:sub_restart: auto
// ...
11:sub_modify: replace
11:sub_restart: auto
// etc, these params added per item
cart: checkout

That should look like this:

sub_modify: replace
sub_restart: auto
cart: checkout

Seeing the following when testing out the quick order form:

GET https://static.www.foxycart.com/beta/foxy-elements/0.3.0/translations/translation/en.json 404

Double translations/translation in there, looks like.

The source and type values on transactions are important enough to visually display, if possible. The type is most helpful for recurring billing, and indicates whether the transaction represents a sub cancel, a sub modification, or a sub renewal. The source indicates whether the transaction is CIT (Customer Initiated Transaction) or MIT (Merchant Initiated).

Possible values are at https://api.foxycart.com/rels/transaction

The type is the more important of the two, and should ideally be visually displayed on the left column transaction list. The source should be displayed on the detail, perhaps above custom fields and attributes. Or combine source and type (and potentially a few other things we're currently missing like user agent, customer IP) into a new box like "Details".

The TaxForm element only accepts integers on the tax rate: https://elements.foxy.dev/?path=/story/forms-taxform--playground

We already have the EmailTemplateForm, but we'll be using those email templates for a bit more with some new functionality (new emailer system allowing for flexible templating and MJML; gift card purchasing + provisioning), so we'll need to allow the email_templates collection to be displayed, and to add and modify additional email_template resources.

Additionally, the email_template resources will have a new template_language parameter with the following values:

"pug", "nunjucks", "handlebars", "twig", "ejs"

Further, some new email templates will allow for MJML to be used.

At a minimum and for now, we need the ability to list templates, display templates, and edit templates.

While we're modifying these elements, let's also look into the possibility of adding a live preview of the email template. This should allow data population from preset samples (email receipt, gift card gift recipient email, abandoned cart reminders) or from specific transactions, and rendering of the templates using the selected template language and MJML. Adding previews might be too much at this point, but would be a huge improvement if it's possible.

On creating a new attribute, let's make sure the "public" ("everyone" in the screenshot above) setting clearly explains the impact, based on the attribute's parent resource. For instance, the text could read as follows, for these resources:

• Customers: "The customer"
• Transactions: "The customer"
• Store: "The world, public"

Actually, it should be "The customer" (or better, equivalent wording) for everything but attributes on the store resource.

Currently on the "Transactions" summary table on a customer detail page, it shows the order total, the name of the product(s), and a link to the receipt. Let's add the date there as well (left column, I think).

Similarly, on the "Subscriptions" tab of that table, let's add the frequency and the next date, if we can.

Product Option Value filter on Transactions does not result in the expected subset of data, but shows all transactions. An example request is sent like this:

?items:item_options[color]=*r*&zoom=items&limit=20&order=transaction_date+desc

I believe it needs to be

?items:item_options:name[color]=*r*&zoom=items,items:item_options&limit=20&order=transaction_date+desc

This works when querying the API directly. For reference: https://api.foxycart.com/docs/cheat-sheet under Name/Value Pairs

"anonymous": "Remain anonynous",

change anonynous to anonymous in src/static/translations/donation/en.json

User recommends changing verbiage to match the email that's sent, and we agree. Change "Get one-time code" to "Get temporary password".

Let's change the Designation functionality to output a select element (single-select, not multi-), and ideally let's allow for optgroup grouping of elements.

When the value is passed to the cart, it should be the string, and not the JSON (so General Fund and not ["General Fund"]).

Also capitalize on the add-to-cart pieces, so it shows capitalized in the cart. (This and other options.)

The foxy-donation web component is beautiful and I am thrilled with it. 🎉
Some quick improvements:

Better Clarity on Recurring Donations

On the "Donate $XX" button, let's either…

• Append (recurring) if the donation is a subscription. This probably would work better with the available space on the button, or…
• Use the language options to make it more natural, like "Donate $XX every month". Or possibly "Donate $XX (every month)". I really like this natural language approach, but we might run into space constraints. We could change the button layout slightly, or shrink the additional text so it's smaller. It'd probably look not great if the button spans 2 lines, though. Maybe some sort of grouping to allow the select and the button to remain separately clickable, but where it's impossible to miss that the "Donate $XX" goes with the frequency.

Maybe something like this?

My initial thought was that the button and the frequency selector were backwards, as the flow of the form should go left to right. But I like the natural language of "Donate $XX just this once" or "Donate $XX every 3 months". But in order to do that, I think we need a slightly improved visual presentation. @dantothefuture @adamjudd Thoughts?

This is super important, imo. It's generally preferred to default to a monthly donation, but it's really easy for donors to miss that and then get upset. And you don't want upset donors. So I think the donation button should be super clear in this regard.

Barring any improvements here, I think we'd need to reverse the button and the frequency selector.

Change the way to trigger a one-time selection

Right now, in order to allow a "Just this once" donation option in the recurring frequency select box, it looks like you must enter 0d. That's a bit weird, and inconsistent with how the /cart endpoint works, where a sub_frequency= (empty value) means it's not recurring. I'd prefer if frequencies='["", "1m", "2m", "3m"]' worked, but if we can't make an empty string function like 0d does, I'd lean towards frequencies='[false, "1m", "2m", "3m"]' or something.

"Anonymous" Improvements

• If "anonymous" is unchecked, no corresponding parameter should be added to the cart. (Currently the donation item in the cart has Anonymous: false as a product parameter.)
• Move the checkbox section above the submit button.

Additional Cart Parameters

I think the following could be added to the "Customizing the cart display" section, which I think we could rename to "Additional Cart Parameters".

Default to Skip the Cart

• By default, this donation form should submit with cart=checkout, in order to bypass the cart and go straight to the checkout. This is a more common approach with donations.
• Allow for displaying the cart by adding support for cart="add". (Allowed cart options are here.)

Add empty Parameter

Per the valid cart parameters, let's allow empty="true" and empty="reset" as valid attributes to foxy-donation.

Foxy has some slick brand new functionality to restrict coupons based on a customer's attributes and/or a customer's active subscriptions. Relatedly, Foxy can also automatically apply coupons on checkout based on those restrictions. This allows things like wholesale discounts (ie. a coupon applying a % discount that requires a specific attribute on the customer) or membership discounts (requiring a specific active subscription).

Docs: https://api.foxycart.com/rels/coupon

The UI should likely group these 3 new parameters:

• customer_auto_apply: Bool (checkbox or radio)
• customer_attribute_restrictions: We may eventually want to allow a filter-building UI, but for now this can just be a string.
• customer_subscription_restrictions: Comma-separated list of strings.

To allow for more flexibility with defining the portal language, we should support detecting the lang attribute if it's on the page already, such as on the html tag. That way the user doesn't need to set the language in multiple places unnecessarily.

We'll be introducing changes to the API to prevent spaces from being entered for codes for gift cards and coupons in the future. To provide a clearer error to users than a generic error, we'll need to introduce client-side validations for preventing spaces as well. This should apply for both bulk adding and generation with prefixes.

I'm guessing this won't be bad to add before the API level change is added that would actually error, if that's right, this can be added whenever it's ready.

Consistency in naming

There are a few inconsistencies with the "quick order form" currently. Let's tidy them up with the following:

• The element should be foxy-items-form. (We like foxy-products-form better but for consistency with the API, let's keep items or @brettflorio will hate it.)
• The products property on the component should change to items.

Consistency in Data?

Currently, items added as <foxy-item /> elements don't show up in the .products property of the element (which we'll rename to .items, per above). Can we make this work? I realize they might be technically different, but I'd "expect" for <foxy-item /> elements to be in the items property, as well as vice versa. Though I realize perhaps that might not actually make sense from a DOM + JS perspective, as they aren't the same things.

QuickOrder#submit fails due to CORS

We can't (currently) do a POST to the /cart endpoint, as we don't support CORS. For now, just make this do a normal POST to /cart.

Default cart=checkout parameter

Add cart="checkout" as a default parameter. Valid options are checkout, empty/null, and add (which is the same as empty/null). By default, this page should send the customer to the checkout.

Default Subscription Parameters

Add sub_modify="replace" and sub_restart="auto" to the output. Allow them to be overridden with empty values or as here: https://wiki.foxycart.com/v/2.0/products/subscriptions#subscription-related_product_options.

Default target parameter

Same as #6. This component may be used inside an iframe (like in Wix), and it should work by default there.

Default to quantity=0

I think we discussed this before, but it looks like it was lost. Two issues:

1. Need to default to quantity 0, not 1, if not specified.
2. Apparently a quantity 0 throws an error? "Invalid product". See it like this:

   const foxyQuickOrderForm = document.querySelector('foxy-quick-form');
   const foxyQuickOrderFormItems = document.querySelectorAll('foxy-quick-form foxy-item');
   for (let i = 0; i < foxyQuickOrderFormItems.length; i++) {
     const item = foxyQuickOrderFormItems[i];
     item.quantity = 0;
   }

Thumbnail Display Options

The goal here would be to allow people to more directly style the thumbnail. For instance:

1. cover and dropshadowed
2. contain and no dropshadow
3. either (cover/contain) and border, not shadow

The best way to do this may be with a CSS shadow part. TBD.

Quick order form products are throwing "The product has no currency" errors in the console. Items shouldn't have a currency. Should only be inherited from the parent.

The foxy-dialog-window should take focus when it appears. Focus should be on the "cancel" button (if present), and tabbing from there should go to the next button.

Not sure if this is related, but if the foxy-dialog-window appears (unfocused) and there's another modal (like for a coupon code, gift cert, custom shipping code) and click delete (to make the foxy-dialog-window appear), then hit enter, the other modal and the foxy-dialog-window both get smaller. Hit enter again and the other modal disappears. Sorta weird :)

Update the docs for the donation widget to use the following file: https://unpkg.com/@foxy.io/elements/dist/cdn/foxy-donation.js

The foxy-customer-form used in the portal needs to be extended with the password update functionality (preferably via templates so that it doesn't end up in the new admin where it isn't supported yet).

Add Swedish translation.