Node flags

[danprince]

Description of new feature

What should the new feature do? For visual features, include an image/mockup of the expected output.

Flags would be a new Cytoscape decoration that allowed nodes to visualise multiple value fields with a set of colors around the outside of the node.

This would involve adding the following style properties to Cytoscape.js.

• flag-property (the name of the property to use for indicating the presence of flags).
• flag-colors (a list of colors to use)
• flag-size (the stroke width of the rendered flag)
• flag-offset (the offset distance between the outside of the node and the center of the flag stroke)

There are two additional properties which might make sense to add here too.

• flag-spacing or flag-gap (control the size of the gap between flag segments)
• flag-mode: "sparse" | "fill" (sparse is the default, "fill" ensures that any present flag segments add up to 360 degrees)

Additional considerations

It might also be worth considering a syntax which explicitly maps from values to colors, to reduce ambiguity around which value will be assigned to which color.

flag-property: "tags";
flag-colors: "foo" "red", "bar" "green", "baz" "yellow";
/* nodes where `data("tags").includes("foo")` will get a "red" flag. */

It's also worth clearly acknowledging that this is a similar feature to the pie styles mentioned here, but takes a different approach that involves enumerating the values and mapping them to a palette, rather than coding a fixed number of slices statically.

Edge cases

• Multiple selectors adding flags to elements (last write wins, never merge sets of flags)
• Number of values exceeding the number of colors (omit flags values that don't have colors)
• Flags around non-circular elements (flags are always rendered as a circle regardless)
• Flag spacing values taking up more than 360

Motivation for new feature

Describe your use case for this new feature.

Given a set of nodes where each node has a multiple value property, flags enable quick scannable visualisation of the presence of values on each element. Here's some example data:

{
  nodes: [
    { data: { id: "java", tags: ["static", "jvm", "imperative"] } },
    { data: { id: "scala", tags: ["static", "functional", "jvm"] } },
    { data: { id: "clojure", tags: ["dynamic", "functional", "jvm"] } },
  ]
}

And here's a suggestion for how flag styles would work:

[tags] {
  flag-property: "tags";
  flag-colors: "red", "green", "blue", "cyan", "magenta", "yellow";
}

And a mockup for how they'd look:

As additional context, here's some of the language and framing we've used for introducing Kumu users to flags.

• The blog post we used to launch flags for Kumu: https://blog.kumu.io/introducing-flags-a-new-decoration-for-multiple-value-fields-88fc879889c8
• Our public facing docs for flags: https://docs.kumu.io/guides/decorate/flags

For reviewers

Reviewers should ensure that the following tasks are carried out for incorporated issues:

• Ensure that the reporter has adequately described their idea. If not, elicit more information about the use case. You should iteratively build a spec together.
• Ensure that the issue is a good fit for the core library. Some things are best done in extensions (e.g. UI-related features that aren't style-related). Some things are best done by app authors themselves -- instead of in Cytoscape libraries.
• The issue has been associated with a corresponding milestone.
• The commits have been incorporated into the unstable branch via pull request. The corresponding pull request is cross-referenced.

[maxkfranz]

@danprince, do you want to schedule a call to discuss some of these issues in more detail? I'm offline this upcoming week, so we could schedule something for the subsequent week. My email is maxkfranz@gmail.com.

[danprince]

Thanks! Replied by email.

[stale]

This issue has been automatically marked as stale, because it has not had activity within the past 14 days. It will be closed if no further activity occurs within the next 7 days. If a feature request is important to you, please consider making a pull request. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale, because it has not had activity within the past 14 days. It will be closed if no further activity occurs within the next 7 days. If a feature request is important to you, please consider making a pull request. Thank you for your contributions.

[maxkfranz]

Summary of previous discussions:

• There should be separate properties for flags, even if they share a similar implementation to pie charts
• Pie charts should be un-deprecated. A new issue for this will be made.

[maxkfranz]

@danprince, do you have an ETA for the PRs for the prior features?

[danprince]

Hey @maxkfranz, afraid we're still catching up on work from the end of last year without a ton of breathing room at the moment.

I can drop you a line when we've got some space again, but it's definitely not going to be in the next few weeks.

[maxkfranz]

@danprince

I'll keep these issues pinned, and I'll keep an eye out for your upcoming email.