cardstack / cardboard

Card Board - a Cardstack application for building narrative experiences

Cardstack App Suite

This is the main repo for Cardstack, an open source application architecture for building cohesive experiences, including payments, on open, decentralized infrastructure.

Join the discussion around developing on the Cardstack framework on Discord, and read our documentation on docs.cardstack.com. (Note: documentation refers to Cardstack v2. The main branch of this respository has in-progress work on v3 of Cardstack.)

Orientation

This is a monorepo. Each directory under packages and cards is distributed as a standalone NPM package under the @cardstack NPM namespace. More information is available in the README.md within each package.

Developing and Testing within this Repo

Local host names

Set up app.cardstack.test and app-assets.cardstack.test to resolve to localhost (127.0.0.1). There are a variety of ways to accomplish this, with the most direct being to edit your /etc/hosts file.

Hub environment variables

See the README in the hub package for environment variables that you'll need to setup.

Fetching waypoint config

To retrieve environment variables for waypoint in a more readable way as an alternative to waypoint config get, you can use the convenience script yarn waypoint-vars.

// prints a table of variables, with values truncated for readability
yarn waypoint-vars
// prints JSON of variables that contain any of the strings provided (case-insensitive), full values
yarn waypoint-vars VAR_NAME1 VAR_NAME2

Javascript dependencies & Typescript compilation

We use volta to manage our global javascript dependencies. In this case, specifically, we use it to manage node and yarn. To use it simply install it following the instructions here: https://docs.volta.sh/guide/getting-started

In development, we use lerna to manage the inter-dependencies of all the packages. To get started:

1. Install node and yarn via volta.
2. yarn global add lerna (use >= 2.0.0 for yarn workspaces integration)
3. lerna bootstrap
4. Launch the typescript compiler with yarn compile --watch
5. Start ember-cli and the hub node server with yarn start and/or run tests with yarn test

Editors

If you use Visual Studio Code and work on the boxel, web-client or ssr-web packages, we recommend the following extensions to make working with glint and gts files better:

• Glint language server integration for VS Code
• VSCode extension for glimmer

Note that you will see TypeScript errors shown twice if you have the built-in VS Code TypeScript extension running as well as the Glint extension. You may also see some spurious errors from the built-in extension, because it does not understand the template tag. It can be beneficial to turn off the built-in TS extension when working purely in a workspace that is configured for glint, since glint is performing a super set of TS validation. To find the built-in extension in the extensions list to disable it, you will need to search for "@builtin typescript".

Understanding the respositories under the Cardstack organization

The following summary offers an overview of where development is currently ongoing at Cardstack. (Note: any projects linked below that are not currently public will become public soon.)

cardstack/card-protocol-xdai

• The Layer 2 contracts for the card protocol live here including
  • PrepaidCardManager contract
  • RevenuePool contract
  • L2 Token contract
  • SPEND token contract
  • BridgeUtilities contract (facilitates token bridge contract)

cardstack/tokenbridge-contracts

• The home bridge and foreign bridge token contracts

https://github.com/cardstack/card-protocol-relay-service

• our gnosis relay service, forked to provide additional prepaid card manager API's that support gasless interactions with our PrepaidCardManager contract

cardstack/safe-transaction-service

• our gnosis transaction service, this was forked to provide transaction service for Sokol (xDai uses the gnosis hosted transaction service)

cardstack/cardstack

• this one! It is our monorepo that contains our CardPay Dapp (as well as eventually cardstack hub runtime). Work on the "card compiler" is also occurring in PRs of this repository. A proof-of-concept for the dapp was developed here: https://github.com/cardstack/card-pay/tree/update-UI-depot

cardstack/cardwallet

• our rainbow wallet fork that supplies our mobile client experience. Currently it is focused around interacting with Layer 1 contracts, eventually we see it as interacting with the Layer2 protocol as well. A proof-of-concept was developed here: https://github.com/cardstack/rainbow/branches

cardstack/infra

• Holds our terraform scripts to provision AWS and cloudflare (and eventually GCP) services for our infrastructure.

cardstack/boxel

• our web UI component library

cardstack/catalog-experiment

• our planned Javascript build tooling and CDN that eliminates the need for running npm/yarn and eliminates the need to maintain a node_modules folder in your web projects

cardstack/animations-experiment

• proof of concept for an animation library that works well with Ember and meets Boxel's motion needs

Project-wide Policy and Community Governance

Cardstack follows semantic versioning. As a young, pre-1.0 project, this means you can continue to expect breaking changes in minor releases. Each package should endeavor to include a CHANGELOG.md once it begins to have a non-trivial number of external users.

We intend to adopt a community RFC governance process for public API changes, based on the Rust and Ember projects. At this pre-1.0 stage, RFCs are optional and changes may still be fast and furious.

Cardstack follows the Ember Community Guidelines, both because we are a proper subset of the existing Ember community and because we wholeheartedly endorse the same values.

cardboard's Issues

When user logs in, the edit mode should be turned off

Application remembers last state and, when user logs in, restores it. However, if users log in on the community page, or different article than they logged off from, they might be brought straight into the edit mode. We should start new session with closed editor, and edit mode off.
This was addressed in cardstack/dotbc#288 and cardstack/dotbc#284
However, I think we need to go deeper than this, and to turn off edit mode when user's session is terminated (either on log off or timeout) as leaving it might bring to unwanted side effects (e.g. user will continue seeing placeholders while being logged off)
Those are 3 related problems and will be tracked in 3 separate issues

This is a follow-up to #46

This issue addresses making sure that new session starts with edit mode off regardless of the editor sidebar being opened or closed

Editor should always take all available height of the page

Even when there are few fields in the editor, it should take entire available height, and there should be no gap between it and the next element other than the padding/margin defined by the layout.

Fields are still randomly disabled for editing a document (this is visible in staging)

Setup github auth

The block mobiledoc menu is chopped off in new edges UI

This is from deck, but i think its probably an issue in the framework itself

Replace Cardstack logo on the community page with Card Board logo

Image to be provided by Nick

When user logs in, new session should be started with editor closed

Application remembers last state and, when user logs in, restores it. However, if users log in on the community page, or different article than they logged off from, they might be brought straight into the edit mode. We should start new session with closed editor, and edit mode off.
This was addressed in cardstack/dotbc#288 and cardstack/dotbc#284
However, I think we need to go deeper than this, and to turn off edit mode when user's session is terminated (either on log off or timeout) as leaving it might bring to unwanted side effects (e.g. user will continue seeing placeholders while being logged off)
Those are 3 related problems and will be tracked in 3 separate issues

This issue addresses starting new session with editor closed

Integrate image transformation service (imagix or cloudinary)

This should ensure uploaded images are served in articles using a web optimized version of the uploaded image that has negligible quality loss.

401 errors issues when uploading images with grant that has only github-writers as able to create cardstack-files

The client is sending the bearer token, but I'm seeing 401 errors in some circumstances (could be related to my dev env hub restarting)...

Animate transitions when opening articles

When opening article from the community page, the image on the embedded card should tween to the hero image on the article page.

Narrative container

A card or component that is a container for other objects/components and embedded cards.
Contents of narrative container can be dynamically added to it, removed, or rearranged.
User should be able to rearrange elements by dragging/dropping them in the right edge.
User adds elements to narrative container by selecting them from library (bottom edge).

UI prototypes TBD

Article card "Satan" theme or alternately "Death"

Article card

Article structure:

We start with simplified structure compared to the article we had earlier in deck.
The set of fields would be:

• Title
• Description, or summary (need to name it correctly - that’s the text that would be displayed in the embedded view)
• Theme: this will be a 1:1 relationship to a Theme content type. Currently we have 3 themes planned. The Theme doesn't necessarily have to be a card--i think it is just a model that is used by the Article card
• Category: this will be a 1:1 relationship to a Category content type. The Category doesn't necessarily have to be a card--i think it is just a model that is used by the Article card
• Author: this should be a json:api relationship to the session user that created the article
• Published date: field appears as a boolean switch, however this actually saves the publish date in the article as a date field when the switch is set to true so we can keep track of the publish date of the article, we should display this date as well next to the switch in the field editor.
• Created date: this is a date field that is set when the article is created--this can not be modified by the user
• Body - this is a mobiledoc field for the article that will be used in place of the narrative container which will be done after ember conf
• Slug: this is the human friendly route name for the article. the slug will default to a dasherized form of the article title

UI prototypes:

• main file: https://sketch.cloud/s/Rd138
• right edge: https://sketch.cloud/s/Rd138/R1qywQx

Community page - Articles

Community page is the index route of card board application.

It contains 3 tabs: "Articles", "Categories", "My Articles". This story concerns the "Articles" tab

In the articles tab, list all published articles sorted by publication date descending.

Hassan: It's really important that articles are NOT retrieved via a query in an ember component. This will create all sorts of ember animated jank (and it ultimately what led us down a very bad path with portfolio). It is really important that the articles are loaded as part of space itself. This means that the community board document will need to fashion a relationship to the articles that are displayed on this page (probably as a result of being published).

suggest using a server-side computed to order the related articles in the correct order based on the articles relationship that the community board has to its articles

Implement index route (app card) UI

(what is this even?)

Article card "Cotton Candy" theme

Style the right edge "header" section to match the UI designs

Currently our right edge header looks like this:

it should look more like this:

Setup Travis deploy to staging

Embed video card within mobiledoc

This should leverage the card picker.

User should be able to upvote or downvote an article from both embedded and isolated views

Community page - Hot

A tab on community page that shows articles sorted by ranking.
We will use reddit story ranking algorithm: https://medium.com/hacking-and-gonzo/how-reddit-ranking-algorithms-work-ef111e33d0d9

Changing the publish date (toggle switch) should add/remove an article from the `boards/community` document's `articles` relationships.

sadly we still don't have query based relationships, so we have to do this manual workaround to add articles to the community board.

Input fields are sporadically disabled in right edge

Input fields that should be editable are sporadically disabled in the right edge. I ran into this a couple times. I suspect the sporadic nature of this is probably the result of some misbehaving async.

Add additional "Medium-esque" rich text formatting to mobiledoc

Comparing Medium editing to what we have implemented so far for mobile doc, I think we are missing:

• section break / hard rule
• preformatted text/code section
  others?

(inserting images is covered in different story)

Open source cardboard

• update SSH deploy keys for travis
• update readme (use portfolio as a reference)
• open source cardboard-data repo too

might also need to regenerate the deploy keys for the github repo too...

Community page - My Articles

Community page is the index route of card board application.

It contains 3 tabs: "Articles", "Categories", "My Articles". This story concerns the "My Articles" tab.

The my articles tab is only shown only to logged in users (hide this tab when logged out). This tab displays articles that were created by user. Includes drafts. Articles are grouped by published status - drafts first, then published. Within each group articles are sorted by creation (drafts) or publication (published) date descending.

Make hero image full-bleed on all themes

Designs specify hero image as full-bleed, current stylesheet has large margins

User sign-in/sign-out UI

Probably should leverage the phrase "Sign in with GitHub", since it more accurate reflects that we are OAuth-ing with GitHub.

Scrollable area of the editor should extend to the bottom of the editor

Currently there is a huge margin between the end of editor's scrollable area and bottom of the editor. Scrollable area should extend to the bottom of the editor

Update placeholder image

Those are new placeholder images to be used in all themes.

One is with + sign, another is without. Both are black, so color manipulation might be needed to better blend with the individual themes.

placeholders.zip

Wait until after we have retrieved token status before showing login button

If you already have a session and you visit the cardboard index route, we actually show the login button while we are checking to see if you have a session. The result is that for people that have a session already they see a login button, and then the login button disappears. Rather we should not show any button until after we have checked the token status. The auth system should be firing an action after the token status is obtained (?). if not, it should be really easy to add an action for that.

Create custom theme picker field editor

New content type example placeholders

This is probably more of a framework feature. But the idea is that when creating a new instance of a card we actually start from a pre-populated card that has a sample images and lorem ipsum that will be used as placeholder fields to give card authors a better idea of what a card can look like, and how to create their card. The example fields are treated as solely placeholder and disappear when the card editor is in the view mode.

Create live code tutorial from cardboard app for ember conf

One of our primary goals for ember conf is to showcase the developer experience of the cardstack framework. To do this, it’s not really enough to just show the finished app, we need to really show how we created the cardboard app. We should:

1. Open source the application
2. Probably fork the repo into a tutorial repo
3. figure out the best way to dissect the cardboard app and create intermediate git tags along with commentary to illustrate how to create a card (probably an article card?), as well as how to embed cards (maybe on the index route?), and perhaps showcase card routing

Setup git data source

Article card "Lake Havasu" theme

This theme evokes the refreshment of water after a long desert journey

Video card

User should be able to specify a YouTube or Vimeo URL for the video. User should also be able to upload a custom poster image for the video.

Image card

A github-writer user can upload an image into cardboard.

I think this is just emulating what we have in deck, where we use the image cardstack/plugin which in turn leverages an s3 datastore for binary blob storage. The title field can be derived from the file name and should be editable. I think we only need an embedded template for this card.

UI prototype: description of image upload UX starts on https://sketch.cloud/s/Rd138/YGqZgEm and continues through https://sketch.cloud/s/Rd138/9Pnlrkz

Card picker updates

In addition to UI updates, I believe we'll also need to be able to support creating an image card and/or a video card based on a user uploading an image from their desktop to use for the image (or poster image in the case of video), as well as specifying the video URL for YouTube/Vimeo video

When user's session is terminated we should make sure the edit mode is turned off

If user logs off (or their session times out) while they are in edit mode (regardless of the editor being opened or closed), user will continue seeing placeholders. Other side effects are possible if permissions are not correctly set up.

This is a followup to #47

We have these same deprecations in cardboard ....

cardstack/portfolio#16

Body editor highlight is wrong color

Clicking "Cancel" on new document fires error

Clicking "Cancel" on new document fires error:

Attempted to handle event `reloadRecord` on <article:null> while in state root.deleted.saved.

Let's just transition back to the cardstack.index route in this scenario for now.

Community page - Categories

Community page is the index route of card board application.

It contains 3 tabs: "Articles", "Categories", "My Articles". This story concerns the "Categories" tab.

The categories tab lists all published articles grouped by categories (tags). One article can belong only to one category. Groups are sorted by number of articles in each category, descending. Within each category articles are sorted by publication date descending.

Animate community page tab transitions

When the user changes the tab on the community page, animate the embedded articles moving to tier new positions (the same as the portfolio app's "currencies" tab).

Setup AWS environment

Animate community page -> article route transitions

animate the route transition from the index route (community page) to the article. We should animate the hero image scaling in size from embedded view to isolated view of the article.

Embed image card within mobiledoc

This should leverage the card picker. We can use the AIA project as a guide for this.

images should be able to have a caption that is unique to the document they are embedded within (in the case where an image is embedded into multiple mobiledocs).

more than one image can be embedded at a time

Header on community page does not stretch the entire page width

non-logged in users shouldn't be able to see unpublished articles

I took a quick look at this, I think it comes down to not incorporating the session in the router.