Adding color modifier support for scheme colors

[dimfeld]

Thank you for reporting an issue, suggesting an enhancement, or asking a question.

We appreciate your feedback - to help the team understand your needs please complete the below template to ensure we have the details to help. Thanks!

Please check out the Docs to see if your question is already addressed there. This will help us ensure our documentation covers the most frequent questions.

Category

• [X] Enhancement
• [ ] Bug
• [ ] Question
• [ ] Documentation gap/issue

Version

Please specify what version of the library you are using: 3.6

Discussion

I'd like to add support for setting color modifiers such as lumMod, lumOff, satMod, shade, tint, and so on when referencing a scheme color. I'm planning to implement this very soon for my own use, so opening this issue for discussion as to how to structure the API when I create the PR.

The actual use case here is that I'm generating templates from existing powerpoint files and then using pptxgenjs to create a new Powerpoint, so it's useful to be able to reuse the same modifiers created by Powerpoint in the source presentations, rather than trying to replicate all those modifiers myself through color calculations.

All of these modifiers are child elements on the schemeClr element, as described at https://c-rex.net/projects/samples/ooxml/e1/Part4/OOXML_P4_DOCX_schemeClr_topic_ID0EBRNJB.html.

My current plan is to do something like this in index.d.ts:

export type HexColor = string
export type ThemeColor = 'tx1' | 'tx2' | 'bg1' | 'bg2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6'
export interface ModifiedThemeColor {
  color: ThemeColor
  shade?: number
  tint?: number
  satMod?: number
  gray?: boolean
  // And all the rest...
}

export type Color = HexColor | ThemeColor | ModifiedThemeColor

The percentage modifiers will follow the existing convention used by the transparency argument of a number from 0 to 100, which is then transformed to the internal "string of thousandths" format when writing the XML. I think this change will only really require updating the typescript definitions and the createColorElement function, so the impact should be fairly small, I think.

Any thoughts?

[gitbrent]

I like where you're going with this and i'll keep an eye on your PR.

[dimfeld]

Sounds good! I’ve been using my fork at work and it’s working great, so I’ll try to get the docs updated over the next few weeks to include the changes.