Implement custom cardstack tag colors and order #2809

yihao03 · 2026-01-29T15:15:23Z

feat: add custom tag order and colors for CardStack component
Refactor and abstract code

What is the purpose of this pull request?

Overview of changes:
Implemented custom tag ordering and color in the CardStack component as mentioned in issue #2783.
Users are now able to include:

<tags>
  <tag name="TagName" color="#RRGGBB" />
  <tag name="TagName" color="<bootstrap_colors>" />
</tags>

to their cardstack. Note that users are not required to include all tags in the custom order; any tags not specified will be appended in default order.
Colors can be specified in hex format or bootstrap color names.

Anything you'd like to highlight/discuss:

Testing instructions:

Pull the branch and run the site locally using markbind serve -d
Navigate to the CardStack component page and verify that the tags appear in the specified custom order with the correct colors.
Optionally, add new cards with tags to ensure that unspecified tags are appended in default order.

Proposed commit message: (wrap lines at 72 characters)
Enable custom tag order and colors in CardStack component

Checklist: ☑️

Updated the documentation for feature additions and enhancements
Added tests for bug fixes or features
Linked all related issues
No unrelated changes

Reviewer checklist:

Indicate the SEMVER impact of the PR:

Major (when you make incompatible API changes)
Minor (when you add functionality in a backward compatible manner)
Patch (when you make backward compatible bug fixes)

At the end of the review, please label the PR with the appropriate label: r.Major, r.Minor, r.Patch.

Breaking change release note preparation (if applicable):

To be included in the release note for any feature that is made obsolete/breaking

Give a brief explanation note about:

what was the old feature that was made obsolete

any replacement feature (if any), and

how the author should modify his website to migrate from the old feature to the replacement feature (if possible).

- Add <tags> syntax parsing in MdAttributeRenderer to extract tag configurations - Implement processCardStackAttributes() to parse <tag> elements with name and color - Add tagConfigs and dataTagConfigs props to CardStack component - Implement tag ordering algorithm that respects custom config order - Add color normalization supporting both hex colors and Bootstrap color names - Update badge rendering with conditional styling (Bootstrap classes vs inline styles) - Add isBootstrapColor() and getTextColor() helper methods for color handling - Apply same color logic to Card component for visual consistency - Add comprehensive test coverage for custom tag ordering and colors - Update documentation with examples for hex colors and Bootstrap color names - Document new <tags> and <tag> element syntax and options

codecov · 2026-01-29T15:19:10Z

Codecov Report

❌ Patch coverage is 90.00000% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.18%. Comparing base (58f396f) to head (ca2b4f3).

Files with missing lines	Patch %	Lines
packages/core/src/html/NodeProcessor.ts	25.00%	3 Missing ⚠️
packages/core/src/html/codeblockProcessor.ts	33.33%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2809      +/-   ##
==========================================
+ Coverage   71.85%   72.18%   +0.33%     
==========================================
  Files         134      134              
  Lines        7340     7449     +109     
  Branches     1563     1622      +59     
==========================================
+ Hits         5274     5377     +103     
- Misses       2020     2026       +6     
  Partials       46       46

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

damithc · 2026-01-29T15:20:19Z

Note that users are not required to include all tags in the custom order; any tags not specified will be appended in default order.

@yihao03 those 'unlisted' tags appear in default order but after the listed tags? Or they appear mixed together with 'listed' tags?

yihao03 · 2026-01-29T15:48:38Z

@damithc they will appear after the specified tags

Harjun751

Commenting on some minor code quality nits here. Code reads good!

Harjun751 · 2026-01-30T03:39:50Z

docs/userGuide/syntax/cardstacks.md


 The example above also illustrates how to use the `keywords` attribute to specify additional search terms for a card.

+### Custom Tag Order and Colors


Minor nit: I wonder if it'd be better (as a reader) for the custom tag order to be above the MRQ cardstack example?

I think I'd prefer it that way but I realize that it might be subjective so if you think this is better/ok that's fine!

packages/core/src/html/MdAttributeRenderer.ts

Harjun751 · 2026-01-30T04:02:11Z

packages/vue-components/src/utils/colors.js

Wow, didn't imagine it'd be this hard to get the colors like that. Cool solution.

gerteck · 2026-01-30T10:11:13Z

docs/userGuide/syntax/cardstacks.md

+
+You can customize the order and colors of tags by using a `<tags>` element inside the `cardstack`:
+
+<include src="codeAndOutputSeparate.md" boilerplate >


Maybe you could consider using `src="codeAndOutput.md"!

<include src="codeAndOutput.md" boilerplate> <variable name="highlightStyle">html</variable> <variable name="code"> Only need to include once if the code is the same </variable> </include>

You could also replace the top example (the existing docs example) with the following as well to incoporate better reuse:

<include src="codeAndOutput.md" boilerplate > <variable name="highlightStyle">html</variable> <variable name="code"> <cardstack searchable> <card header="**Winston Churchill**" tag="Success, Perseverance"> Success is not final, failure is not fatal: it is the courage to continue that counts </card> <card header="**Albert Einstein**" tag="Success, Perseverance"> In the middle of every difficulty lies opportunity </card> <card header="**Theodore Roosevelt**" tag="Motivation, Hard Work"> Do what you can, with what you have, where you are </card> <card header="**Steve Jobs**" tag="Happiness, Mindset"> Your time is limited, so don’t waste it living someone else’s life </card> </cardstack> </span> </variable>

interesting! when would codeAndOutputSeparate.md be useful then?

It's useful for the question quiz example for instance

in the code block, we can show  and not have to show the entire code block of the questions.

Copilot

Pull request overview

This PR adds support for custom tag ordering and colors in the CardStack component, wired end‑to‑end from Markdown syntax through the core HTML processor to the Vue UI, with supporting utility functions and documentation.

Changes:

Introduced shared color utilities (BADGE_COLOURS, isBootstrapColor, getTextColor, normalizeColor, MIN_TAGS_FOR_SELECT_ALL) and HTML escape helpers for both core and Vue packages.
Extended CardStack and Card Vue components to consume serialized tag configuration metadata (data-tag-configs / tagConfigs) and render tags in custom order with either Bootstrap or hex colors.
Updated the core Markdown/HTML processing pipeline (MdAttributeRenderer, NodeProcessor) to parse <tags><tag .../></tags> blocks in cardstack, serialize them into a safely escaped data-tag-configs attribute, and documented the feature with examples and tests.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`packages/vue-components/src/utils/utils.js`	Adds `escapeHTML`/`unescapeHTML` helpers for safely handling serialized JSON in attributes on the Vue side, mirroring the core escape behavior.
`packages/vue-components/src/utils/colors.js`	Introduces reusable badge color utilities (Bootstrap mapping, contrast-aware text color, normalization) used by `CardStack`/`Card`.
`packages/vue-components/src/cardstack/CardStack.vue`	Refactors tag color constants into shared utilities, adds `tagConfigs`/`dataTagConfigs` props, parses and applies custom tag order/colors to `tagMapping`, and adjusts rendering to support both Bootstrap and hex colors.
`packages/vue-components/src/cardstack/Card.vue`	Updates tag badge rendering to use the new color utilities so individual cards reflect the configured tag colors consistently.
`packages/vue-components/src/__tests__/utils.spec.js`	Adds unit tests for the Vue `escapeHTML`/`unescapeHTML` functions, including JSON and entity round‑trip behavior.
`packages/vue-components/src/__tests__/colors.spec.js`	Covers `BADGE_COLOURS`, `MIN_TAGS_FOR_SELECT_ALL`, `isBootstrapColor`, `getTextColor`, and `normalizeColor` to ensure color handling stays consistent.
`packages/vue-components/src/__tests__/CardStack.spec.js`	Extends `CardStack` tests to verify custom tag ordering, hex and Bootstrap color application, fallback behavior for unconfigured tags, and robustness to invalid tag configs.
`packages/core/test/unit/utils/escape.test.ts`	Adds tests for the core `escapeHTML` implementation ensuring correct escaping of special characters and entities.
`packages/core/test/unit/html/MdAttributeRenderer.test.ts`	Introduces tests around `processCardStackAttributes` for parsing `<tags>` blocks, building `data-tag-configs`, escaping values correctly, and removing the `<tags>` node.
`packages/core/src/utils/escape.ts`	Implements the core `escapeHTML` function used when serializing tag configuration JSON into HTML-safe attributes.
`packages/core/src/html/NodeProcessor.ts`	Hooks `cardstack` nodes into the attribute-processing pipeline by delegating to `MdAttributeRenderer.processCardStackAttributes`.
`packages/core/src/html/MdAttributeRenderer.ts`	Adds `processCardStackAttributes` to extract `<tag>` definitions under `<tags>`, build a typed config array, escape it, and set `data-tag-configs` on the `cardstack` node.
`docs/userGuide/syntax/cardstacks.md`	Documents the new `<tags>/<tag>` syntax, explains ordering and color options (hex and Bootstrap names), and adds illustrative examples with rendered output.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

packages/vue-components/src/cardstack/CardStack.vue

gerteck

Thanks @yihao03 for this PR, great work! Added some comments

packages/core/src/html/MdAttributeRenderer.ts

packages/vue-components/src/cardstack/CardStack.vue

…tion

Copilot

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-01T17:14:03Z

packages/vue-components/src/utils/colors.js

+export function isBootstrapColor(color) {
+  return BADGE_COLOURS.some(c => c === color);
+}
+
+export function getTextColor(backgroundColor) {
+  if (!backgroundColor || backgroundColor.startsWith('bg-')) {
+    return '#000';
+  }


isBootstrapColor only returns true for values that exactly match entries in BADGE_COLOURS, which means color values that start with bg- but are not in that fixed list (e.g. bg-warning or custom bg-custom) are treated as non‑Bootstrap colors and end up being applied via backgroundColor inline style, which produces invalid CSS and incorrect rendering. To keep behaviour consistent with normalizeColor (which explicitly treats any bg- value as a Bootstrap class) and avoid this bug, consider changing isBootstrapColor to detect Bootstrap classes more generically (for example by checking color.startsWith('bg-')), rather than restricting it to the fixed palette.

Copilot · 2026-02-01T17:14:03Z

packages/vue-components/src/utils/utils.js

+export function escapeHTML(htmlStr) {
+  return String(htmlStr)
+    .replace(/&(?!\w+;)/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

-  return {style: mainStyle, icon: iconStyle};
+export function unescapeHTML(htmlStr) {
+  return String(htmlStr)
+    .replace(/&quot;/g, '"')
+    .replace(/&gt;/g, '>')
+    .replace(/&lt;/g, '<')
+    .replace(/&amp;/g, '&');
 }


There are now two independent implementations of HTML escaping logic: escapeHTML/unescapeHTML in packages/vue-components/src/utils/utils.js and escapeHTML in packages/core/src/utils/escape.ts, which must remain behaviourally identical for cardstack tag configs to round‑trip correctly between server and client. To reduce the risk of future divergence and subtle bugs, consider centralising this logic (or at least adding a shared test/contract) so that both code paths share the same implementation or are clearly validated against each other.

Do you want to consider using

https://www.npmjs.com/package/html-entities

This way, we just have to make sure that the package is at the same version for both vue component and core package.

docs/userGuide/syntax/cardstacks.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gerteck

logic lgtm, just some file structure changes for clarity of responsibilties

gerteck · 2026-02-02T05:47:51Z

packages/core/src/html/MdAttributeRenderer.ts

  }

+  // eslint-disable-next-line class-methods-use-this
+  processCardStackAttributes(node: MbNode) {


Consider moving this method into its own class or file (e.g. cardStackProcessor.ts in /html, since it does not do any markdown rendering as in MdAttributeRenderer.

The current structure seems to suggest processCardStackAttributes processes markdown, while in actuality it is manipulating the HTML Dom and injecting attributes independent of markdown syntax.

For e.g. headerProcessor, footnoteProcessor are either their own class or export their own functions.

Otherwise, the logic for the function lgtm

…ub.com:yihao03/markbind into feat/cardstack-tag-order-colors-implementation

Now has its own file in the html package this is more fitting as the function technically doesn't touch md attributes

…tion

gerteck · 2026-02-02T16:01:31Z

packages/core/src/html/MdAttributeRenderer.ts

    this.processSlotAttribute(node, 'header', true);
  }

+  // eslint-disable-next-line class-methods-use-this


leftover code

gerteck · 2026-02-02T16:01:47Z

packages/core/src/html/MdAttributeRenderer.ts

  has,
 };

+export type CardStackTagConfig = { name: string; color?: string };


gerteck · 2026-02-02T16:02:18Z

packages/core/src/html/MdAttributeRenderer.ts

                                  isInline: boolean, slotName = attribute): void {
    const hasAttributeSlot = node.children
-        && node.children.some(child => getVslotShorthandName(child) === slotName);
+      && node.children.some(child => getVslotShorthandName(child) === slotName);


^ can revert this so it does not show up in the pr changes

gerteck · 2026-02-02T16:03:01Z

packages/core/src/html/cardStackProcessor.ts

@@ -0,0 +1,55 @@
+import { encode } from 'html-entities';
+import { MbNode, NodeOrText } from '../utils/node';
+import { CardStackTagConfig } from './MdAttributeRenderer';


should this be defined and exported here?

gerteck · 2026-02-02T16:07:05Z

packages/core/test/unit/html/MdAttributeRenderer.test.ts

should this file be renamed

gerteck · 2026-02-02T16:08:40Z

packages/vue-components/src/utils/utils.js

 // @params (function, delay_prop or value, default_value)
-export function delayer (fn, varTimer, ifNaN = 100) {
-  function toInt (el) { return /^[0-9]+$/.test(el) ? Number(el) || 1 : null }
+export function delayer(fn, varTimer, ifNaN = 100) {


try to minimize whitespace changes in PRs because it adds noise to the PR file changes,

for instance, i had to look through all whitespace changes to find that there were no functional changes in this file

Linting PRs should be a separate PR with only whitespace changes, for instance

yihao03 added 2 commits January 29, 2026 17:00

Refactor and abstract code

7698efd

Add tests

a2801bc

yihao03 requested review from Harjun751, MoshiMoshiMochi and gerteck and removed request for gerteck January 30, 2026 02:18

yihao03 self-assigned this Jan 30, 2026

yihao03 added the c.Feature 🚀 label Jan 30, 2026

Harjun751 reviewed Jan 30, 2026

View reviewed changes

gerteck requested a review from Copilot January 30, 2026 10:14

Copilot started reviewing on behalf of gerteck January 30, 2026 10:14 View session

gerteck reviewed Jan 30, 2026

View reviewed changes

Copilot AI reviewed Jan 30, 2026

View reviewed changes

packages/vue-components/src/cardstack/CardStack.vue Outdated Show resolved Hide resolved

gerteck requested changes Jan 30, 2026

View reviewed changes

yihao03 added 4 commits February 1, 2026 19:36

Remove redundant code in userguide

814f1b4

Update type and typecheck

2c8fa85

Refactor to avoid circular reference

0626ecb

Merge branch 'master' into feat/cardstack-tag-order-colors-implementa…

a718071

…tion

yihao03 requested a review from gerteck February 1, 2026 14:51

gerteck requested a review from Copilot February 1, 2026 17:09

Copilot started reviewing on behalf of gerteck February 1, 2026 17:09 View session

Copilot AI reviewed Feb 1, 2026

View reviewed changes

Update docs/userGuide/syntax/cardstacks.md

2ffbfb8

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

gerteck requested changes Feb 2, 2026

View reviewed changes

Merge branch 'feat/cardstack-tag-order-colors-implementation' of gith…

70157a7

…ub.com:yihao03/markbind into feat/cardstack-tag-order-colors-implementation

yihao03 added 5 commits February 2, 2026 22:48

Move processCardStackAttributes from MdAttributeRenderer

f070f94

Now has its own file in the html package this is more fitting as the function technically doesn't touch md attributes

Update tests

b66f99c

Lint

21370b4

Replace html escape functions with html-entities library

943bdbc

Merge branch 'master' into feat/cardstack-tag-order-colors-implementa…

ca2b4f3

…tion

gerteck requested changes Feb 2, 2026

View reviewed changes


		The example above also illustrates how to use the `keywords` attribute to specify additional search terms for a card.

		### Custom Tag Order and Colors


		You can customize the order and colors of tags by using a `<tags>` element inside the `cardstack`:

		<include src="codeAndOutputSeparate.md" boilerplate >

Implement custom cardstack tag colors and order #2809

Are you sure you want to change the base?

Implement custom cardstack tag colors and order #2809

Conversation

yihao03 commented Jan 29, 2026

Uh oh!

codecov bot commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

damithc commented Jan 29, 2026

Uh oh!

yihao03 commented Jan 29, 2026

Uh oh!

Harjun751 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

gerteck left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gerteck left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

codecov bot commented Jan 29, 2026 •

edited

Loading