Support strings as section references

[antoniozzo]

I think the SC5 template should support strings as section references:

// Styleguide 1.0
// - or -
// Styleguide Forms.Checkbox

Numbers are hard to maintain if you keep moving stuff around or adding. This is something that the kss-node template have.

If this is already implemented but not documented, please tell me how to do it.

[hannu]

Thank you. This is a bug in our KSS block detection. We'll look into it.

[cognivator]

+1

[cognivator]

@hannu @cyberixae,

I'm taking a run at this bug. Let me know if I should be coordinating with someone on your core team regarding the following findings and choices.

Identifying kss blocks

Kss-splitter identifies a kss block by checking the Styleguide reference for digits only. This is a simple RegExp fix to allow alpha as well. Seems low risk and obvious.

Section sorting

Next up is the issue of sorting the sections. Below you'll find my assessment of the kss-node sorter, and the options we have in SC5 for achieving the same sort outcome.

Native kss-node section sorting

Kss-node makes some assumptions about the section sort in KssStyleguide

1. it has access to all the sections via an array of KssSection objects
2. the weight parameter in a kss comment overrides normal alpha sort when Styleguide references are strings
3. string references are hard to pass around (from their docs,) so after the first pass to sort, it makes a second pass to derive a traditional numerical reference for each section, surfaced as .autoincrement

Taking each assumption in turn, Access to all kss sections - SC5 sends only one kss block / file to the kss-node parser at a time. Having violated the first assumption above, the kss-node sorter can't produce the right results for SC5. Weight parameter - the kss-node sorting algorithm modifies a standard alpha sort by using the weight parameter. This prevents us from using an off-the-shelf sorting library. Re-using the kss-node sorter would be ideal. Autoincrement reference - while tempting to use the .autoincrement value for our own purposes, it has the flavor of an internal API (use at own risk), and is also inaccurate without having all sections available at once (see the first assumption.) Also, kss-node leaves the reference intact and stores a supplementary autoincrement property; we need the reverse to keep the SC5 codebase refactoring to a minimum (store the original string reference as a supplementary property, and replace the reference with the derived number.)

Sorting Options

At base, we can either try to use the kss-node sorter by one of several methods, or write our own. Re-using kss-node seems the best option, it's just a matter of how.

In-place

Package up SC5's section list late in processing, re-construct the data structure KssStyleguide expects from its own internal parser, and let kss-node work some magic.

Pros

• we don't maintain our own sorting code, when kss-node has already figured out the weight parameter modifications
• we stay "in-sync" with kss-node specs by using their code directly

Cons

• we have to conjure a data structure we wouldn't normally use
• the sorter, while a public method on KssStyleguide, cannot be passed a data structure in its current form; we would have to hydrate a KssStyleguide first, which has its own overhead and side-effects
• we tie our implementation to theirs in potentially unsightly ways - we are required to know "too much" about their internal data structures and APIs among their internal classes

Copy and maintain

Copy and modify the kss-node algorithm in the SC5 codebase. I've identified a reasonable replacement vector in SC5 is the .bySectionReference sort comparator.

Pros

• we make use of a known sorting algorithm that includes the .weight parameter override for string-based Styleguide references
• we avoid strong coupling to the kss-node codebase and internal APIs
• we use our existing data structures and method signatures

Cons

• we sign up for long-term maintenance of the sorting algorithm, IF the goal is to continue to track kss-node's interpretation of the kss spec
• we must also run our own "autoincrement-esque" re-assignment for the kss reference in the SC5 data model
• license issues (???)

Recommendation

I'm pursuing the second option above, "Copy and maintain". Let me know if you have other alternatives in mind.

[hannu]

Hi. Nice to see that you are already very familiar with the current code base.

I would go with the "Copy and maintain" option. Since the sorting logic should easy enough to implement and maintain, we do not need to replicate too much internal kss-node logic. If we would choose to pass all KSS blocks at once to kss-node it would require huge internal changes and we still need to split the KSS blocks to find related CSS and variables.

Even with the "Copy and maintain" option, we still support all other KSS features that are not dependent on other sections.

Kind of unrelated note, but good to know: Currently we use modules/kss-additional-params.js to parse additional parameters in the KSS blocks. This module also cleans up params from the KSS markup before passing block to the kss-node. As far as I know, the current version of kss-node supports additional parameters and this module is not needed anymore and should be removed at some point.

[cognivator]

Thanks, @hannu.

I've made good progress, and am chasing down some unit test failures (regression) when multiple files are involved. Still on the copy and maintain path, and already encapsulated the kss-node sort algorithms in a KssNodeSorter class.

A couple of questions arise around intended behavior...

duplicate references

Currently this causes a failure when numeric references are used. This seems a reasonable response, since reshuffling the references is both difficult and unexpected especially since the resulting sections wouldn't match the source. With string references, it would be possible to continue assigning derived numerics across duplicate references. This introduces a behavioral inconsistency between the use of numerics v. strings, but perhaps a useful one?

combination of numerics and strings

It seems the SC5 UI has high expectations of numeric references, which is why I'm converting string references to the derived numerics. Doing so, however, makes supporting both numeric and string references in the source kss for a single styleguide problematic. Because there is no attempt to avoid existing numeric references when deriving numerics from the string references, the chance of duplicating the original numerics is almost assured. (Kss-node doesn't encounter this problem since the original references are used directly in their styleguide, rather than the derived numerics. Essentially, the original numerics are considered strings in such a "mixed mode.")

Some options,

1. Allow 'mixed mode' by one of the following methods:
   1. do the same as kss-node, and allow string references in the UI (refactoring SC5 UI, and the unique page url assignment if necessary)
   2. avoid duplicate references by giving precedence to the original numerics when deriving from strings.
2. Disallow "mixed mode" which carries two additional implications,
   1. References
      • Us the original numerics when in 'numeric' mode, and the derived numerics when in 'string' mode
   2. Failure
      • Decide on one of the following (or...?)
        1. Throw when mixed mode is discovered during sort processing, similar to how duplicate references are handled
        2. Allow sub-optimal / undefined behavior, and rely on documenting the limitation (No. Bad.)

Thoughts?

[maeertin]

+1

[Npahlfer]

+1

[paulobarcelos]

+1

[emilsall]

+1

[vincentboiardt]

+1

[samny]

+1

[gisu]

+1

[lauraluo]

+1

[levito]

+1

[amauryhubault]

+1

[elebescond]

+1

[tonioriol]

+1

[Albinwikander]

+1

[irisSchaffer]

+1

[kvzivn]

+0

[ayjee]

+1

[patriziosotgiu]

+1

[birdfoot]

+1

[nicodeclercq]

+1

[DanielaValero]

Hello everyone,

I have already a branch, in which I am preparing this feature. In the mean time, instead of adding more comments with +1 would you add a reaction to the first comment, with the +1 icon version?

It would help a lot to keep the ticket clean.