@animus-ui/theming 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Aaron Robb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,162 @@
+# `@animus-ui/theming`
+
+In order to use animus with your custom theme you must redeclare the emotion global `Theme`.
+
+```tsx
+import { theme } from './theme';
+
+export type ThemeShape = typeof theme;
+
+declare module '@emotion/react' {
+  export interface Theme extends ThemeShape {}
+}
+```
+
+To help you create this strongly typed theme we've provided a few helpers to make it easier to progressively create a strongly typed and dynamic theme that will adhere to the correct types.
+
+## `createTheme()`
+
+This method is a set of chainable methods that will progressively add tokens, relationships, and core features to a theme object.
+
+While many frameworks restrict theme scales to very specific sets we leave many of the particulars up to the user to define as the only key that we require for baseline functionality is `breakpoints`.
+
+We do however offer optional but opinionated handling of both `colors` + `colorModes`.
+
+### Usage
+
+```tsx
+import { ThemeProvider, Global, css } from '@emotion/react';
+
+export const theme = createTheme({
+  breakpoints: {
+    xs: '@media screen and (min-width: 480px)',
+    sm: '@media screen and (min-width: 768px)',
+    md: '@media screen and (min-width: 1024px)',
+    lg: '@media screen and (min-width: 1200px)',
+    xl: '@media screen and (min-width: 1440px)',
+  },
+  spacing: {
+    4: '0.25rem',
+    8: '0.5rem',
+    12: '0.75rem',
+    16: '1rem',
+  },
+})
+  .addColors({
+    white: '#ffffff',
+    hyper: '3A10E5',
+    navy: '#10162f',
+    yellow: '#FFD300',
+  })
+  .createColorModes('light', {
+    light: {
+      primary: 'hyper',
+      secondary: 'navy',
+      text: 'navy',
+      background: 'white',
+    },
+    dark: {
+      primary: 'yellow',
+      secondary: 'white',
+      text: 'white',
+      background: 'navy',
+    },
+  })
+  .addVariables('spacing')
+  .build();
+
+/**
+ * To use your new theme you must do 3 things.
+ * 1. Declare your theme shape as the emotion theme.
+ * 2. Wrap your application in a ThemeProvider
+ * 3. And add your variables to the global styles.
+ */
+
+export type ThemeShape = typeof theme;
+
+declare module '@emotion/react' {
+  export interface Theme extends ThemeShape {}
+}
+
+const App = () => {
+  return (
+    <ThemeProvider theme={theme}>
+      <Global styles={css({ ':root': root })} />
+      <Global styles={css({ ':root': colorMode })} />
+      <Component />
+    </ThemeProvider>
+  );
+};
+```
+
+### Methods
+
+A theme creator method that progressively build and decorate a type safe theme object. This allows us to create a build separate themes that will be compatible with animus props. The raw theme must have a valid breakpoint scale to ensure breakpoint variable serialization.
+
+**Standard Methods** - These are the core methods to add scales and variables to the theme object
+
+- `addScale(scaleKey, updateFunction)` - Adds a set of tokens to the theme on the provided scale key. The current theme can be used as reference for this new scale for shared value reference.
+- `updateScale(scaleKey, updateFunction)` - Updates an existing scale with new or computed value without them being explicitly declared. This can also be used to update or extend a theme for a different context (restrictions or expansions).
+- `createScaleVariables(scaleKey)` - Takes a top level key of the current theme and serialized them as CSS variables. The theme will include references to CSS Variables and adds the actual token values to the root scope of our variable object.
+
+**Special Methods** - these have specific behavior that is non standard, these are both required for all features to work
+
+- `addColors(tokens)` - Adds color tokens to the theme and creates root color variables by default. Calling this method required to access `getColorValue` and `addColorModes`. You will not be able to add colors through `addScale` and be able to build color modes as they have different internal behaviors. However if you do not want either features you may use it without any issue.
+- `addColorModes(initialMode, colorModes)` - This method takes a configuration of color aliases that have semantic meaning between contexts such as `light` and `dark` modes. This will take a map of modes and an initial mode.
+  - Colors must exist on the theme for this to work, call this method after `addColors` to ensure this works correctly.
+  - This creates CSS variables for the initial color mode and adds them to the specific bucket at the root scope and ensures that nested color variable references behave correctly (if variables change these will too).
+
+**Finalization**
+
+- `build()` - Called when all mutations are finished and we get the finalized and fully typed design system objects.
+
+# Other Utilities
+
+These are some under the hood utilities that you can use outside of root theme creation. `createTheme` may use some of these internally but they can also be used independently.
+
+## `serializeTokens()`
+
+### Arguments
+
+- `tokens` any set of tokens.
+- `prefix` a string to prefix any tokens
+- `theme` to reference existing tokens specifically for breakpoints.
+
+This method predictably maps token literal values to CSS variables. We use this to store relational or contextual information in a single reference.
+
+### Usage
+
+```tsx
+const { tokens, variables } = serializeTokens({
+  black: '#000000',
+  white: '#FFFFFF'
+}, 'color', {});
+
+// tokens
+{ black: 'var(--color-black)', white: 'var(--color-white)' }
+
+// variables
+{ '--color-black': '#000000', '--color-white': '#FFFFFF' };
+```
+
+This will also work with possible nested selectors like breakpoints:
+
+```tsx
+const {
+  tokens, //An object of the same keys as the first argument but with values that point to variable references
+  variables // Valid CSS variables that are prefixed with the same keys.
+} = serializeTokens({
+  height: { _: '4rem', lg: '5rem' },
+}, 'header', theme);
+
+// tokens
+{ height: 'var(--header-height)' }
+
+// variables
+{
+  '--header-height': '4rem',
+  '@media screen and (min-width: 1024px)': {
+    '--header-height': '5rem',
+  }
+}
+```

package/babel.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  extends: '../../babel.config.js',
+  include: ['./src/**/*.ts', './src/**/*.tsx'],
+  ignore: ['./**/*.d.ts', '__tests__'],
+};

package/dist/core/ThemeBuilder.d.ts

@@ -0,0 +1,34 @@
+import { Breakpoints } from '@animus-ui/core';
+/**
+ * 1. Breakpoints
+ * 2. Scales
+ * 3. Tokens
+ * 4. Variables
+ * 5. Colors
+ * 6. Color Modes
+ */
+export declare class ThemeWithAll<Bps, Scales, Tokens, Vars> {
+    breakpoints: Bps;
+    scales: Scales;
+    tokens: Tokens;
+    variables: Vars;
+    constructor(breakpoints: Bps, scales: Scales, tokens: Tokens, vars: Vars);
+    addScale(): ThemeWithAll<Bps, Scales, Tokens, Vars>;
+    build(): {
+        breakpoints: Bps;
+    } & Scales & {
+        _tokens: Tokens;
+        _variables: Vars;
+    };
+}
+export declare class ThemeWithRawColors<Bps extends Breakpoints, Scales, Tokens, Vars> extends ThemeWithAll<Bps, Scales, Tokens, Vars> {
+    constructor(breakpoints: Bps, scales: Scales, tokens: Tokens, vars: Vars);
+    addColorModes(): ThemeWithAll<Bps, Scales, Tokens, Vars>;
+}
+export declare class ThemeWithBreakpoints<Bps extends Breakpoints> extends ThemeWithAll<Bps, {}, {}, {}> {
+    constructor(breakpoints: Bps);
+    addColors(): ThemeWithRawColors<Bps, {}, {}, {}>;
+}
+export declare class ThemeUnitialized {
+    addBreakpoints<Bps extends Breakpoints>(breakpoints: Bps): ThemeWithBreakpoints<Bps>;
+}

package/dist/index.cjs.js

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e=require("lodash");function t(s,r){return Object.keys(s).reduce(((o,h)=>{const i=r?`${r}${"_"===h?"":`-${h}`}`:h,a=s[h];return e.isObject(a)?{...o,...t(a,i)}:{...o,[i]:s[h]}}),{})}const s=(t,s,r)=>{const o={},h={};return Object.keys(t).forEach((i=>{const a=`--${s}-${i}`;o[i]=`var(${a})`,e.merge(h,((t,s,r)=>{if(e.isObject(t)){const{_:e,base:o,...h}=t,i={[s]:e??o};if(r){const{breakpoints:e}=r;Object.keys(e).forEach((t=>{i[e[t]]={[s]:h[t]}}))}return i}return{[s]:t}})(t[i],a,r))})),{tokens:o,variables:h}};class r{#e={};constructor(e){this.#e=e}createScaleVariables(t){const{variables:r,tokens:o}=s(this.#e[t],t,this.#e);return this.#e=e.merge({},this.#e,{[t]:o,_variables:{root:r},_tokens:{[t]:this.#e[t]}}),this}addColors(r){const o=t(r),{variables:h,tokens:i}=s(o,"color",this.#e);return this.#e=e.merge({},this.#e,{colors:i,_variables:{root:h},_tokens:{colors:o}}),this}addColorModes(r,o){const h=e.mapValues(o,(e=>t(e))),{tokens:i,variables:a}=s(e.mapValues(e.merge({},this.#e.modes?.[r],h[r]),(e=>this.#e.colors[e])),"color",this.#e),m=e=>this.#e._tokens?.colors?.[e];return this.#e=e.merge({},this.#e,{colors:i,modes:h,mode:r,_getColorValue:m,_variables:{mode:a},_tokens:{modes:e.mapValues(h,(t=>e.mapValues(t,m)))}}),this}addScale(s,r){return this.#e=e.merge({},this.#e,{[s]:t(r(this.#e))}),this}updateScale(t,s){return this.#e=e.merge({},this.#e,{[t]:s(this.#e[t])}),this}build(){return e.merge({},this.#e,{_variables:{},_tokens:{}})}}exports.ThemeBuilder=r,exports.createTheme=function(e){return new r(e)},exports.flattenScale=t,exports.serializeTokens=s;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './utils';

package/dist/index.esm.js

@@ -0,0 +1 @@
+import{isObject as e,merge as t,mapValues as s}from"lodash";function o(t,s){return Object.keys(t).reduce(((r,h)=>{const i=s?`${s}${"_"===h?"":`-${h}`}`:h,n=t[h];return e(n)?{...r,...o(n,i)}:{...r,[i]:t[h]}}),{})}const r=(s,o,r)=>{const h={},i={};return Object.keys(s).forEach((n=>{const a=`--${o}-${n}`;h[n]=`var(${a})`,t(i,((t,s,o)=>{if(e(t)){const{_:e,base:r,...h}=t,i={[s]:e??r};if(o){const{breakpoints:e}=o;Object.keys(e).forEach((t=>{i[e[t]]={[s]:h[t]}}))}return i}return{[s]:t}})(s[n],a,r))})),{tokens:h,variables:i}};class h{#e={};constructor(e){this.#e=e}createScaleVariables(e){const{variables:s,tokens:o}=r(this.#e[e],e,this.#e);return this.#e=t({},this.#e,{[e]:o,_variables:{root:s},_tokens:{[e]:this.#e[e]}}),this}addColors(e){const s=o(e),{variables:h,tokens:i}=r(s,"color",this.#e);return this.#e=t({},this.#e,{colors:i,_variables:{root:h},_tokens:{colors:s}}),this}addColorModes(e,h){const i=s(h,(e=>o(e))),{tokens:n,variables:a}=r(s(t({},this.#e.modes?.[e],i[e]),(e=>this.#e.colors[e])),"color",this.#e),c=e=>this.#e._tokens?.colors?.[e];return this.#e=t({},this.#e,{colors:n,modes:i,mode:e,_getColorValue:c,_variables:{mode:a},_tokens:{modes:s(i,(e=>s(e,c)))}}),this}addScale(e,s){return this.#e=t({},this.#e,{[e]:o(s(this.#e))}),this}updateScale(e,s){return this.#e=t({},this.#e,{[e]:s(this.#e[e])}),this}build(){return t({},this.#e,{_variables:{},_tokens:{}})}}function i(e){return new h(e)}export{h as ThemeBuilder,i as createTheme,o as flattenScale,r as serializeTokens};

package/dist/utils/createTheme.d.ts

@@ -0,0 +1,53 @@
+import { CSSObject, AbstractTheme } from '@animus-ui/core';
+import { LiteralPaths } from './flattenScale';
+import { KeyAsVariable } from './serializeTokens';
+import { ColorModeConfig, Merge, MergeTheme, PrivateThemeKeys } from './types';
+export declare class ThemeBuilder<T extends AbstractTheme> {
+    #private;
+    constructor(baseTheme: T);
+    /**
+     *
+     * @param key A key of the current theme to transform into CSS Variables and Variable References
+     * @example .createScaleVariables('fontSize')
+     */
+    createScaleVariables<Key extends keyof Omit<T, 'breakpoints'> & string>(key: Key): ThemeBuilder<MergeTheme<T, PrivateThemeKeys, Record<Key, Record<Key, KeyAsVariable<T[Key], Key>>>>>;
+    /**
+     *
+     * @param colors A map of color tokens to add to the theme. These tokens are immediately converted to CSS Variables `--color-${key}`.
+     * @example .addColors({ navy: 'navy', hyper: 'purple' })
+     */
+    addColors<Colors extends Record<string, string | number | CSSObject>, NextColors extends LiteralPaths<Colors, '-'>>(colors: Colors): ThemeBuilder<MergeTheme<T & PrivateThemeKeys, Record<'colors', KeyAsVariable<NextColors, 'color'>>>>;
+    /**
+     *
+     * @param initialMode A key of the object passed for modes.  This sets the default state for the theme and transforms the correct variables.
+     * @param modes A map of color modes with keys of each possible mode with a value of alias to color keys.  This must be called after `addColors`
+     * @example .addColorModes('light', { light: { primary: 'hyper' }, { dark: { primary: 'navy' } } })
+     */
+    addColorModes<Modes extends string, InitialMode extends keyof Config, Colors extends keyof T['colors'], ModeColors extends ColorModeConfig<Colors>, Config extends Record<Modes, ModeColors>, ColorAliases extends {
+        [K in keyof Config]: LiteralPaths<Config[K], '-', '_'>;
+    }>(initialMode: InitialMode, modeConfig: Config): ThemeBuilder<MergeTheme<T & PrivateThemeKeys, {
+        colors: KeyAsVariable<LiteralPaths<Config[keyof Config], '-', '_'>, 'colors'> & T['colors'];
+        modes: Merge<T['modes'], ColorAliases>;
+        mode: keyof Config;
+        _getColorValue: (color: keyof T['colors']) => string;
+    }>>;
+    /**
+     *
+     * @param key A new key of theme
+     * @param createScale A function that accepts the current theme and returns a new object of scale values.
+     * @example .addScale('fonts', () => ({ basic: 'Gotham', cool: 'Wingdings' }))
+     */
+    addScale<Key extends string, Fn extends (theme: T) => Record<string | number, string | number | Record<string, string | number>>, NewScale extends LiteralPaths<ReturnType<Fn>, '-'>>(key: Key, createScale: Fn): ThemeBuilder<MergeTheme<T, Record<Key, NewScale>>>;
+    /**
+     *
+     * @param key A current key of theme to be updated with new or computed values
+     * @param updateFn A function that accepts an argument of the current values at the specified keys an returns a map of new values to merge.
+     * @example .updateScale('fonts', ({ basic }) => ({ basicFallback: `{basic}, Montserrat` }))
+     */
+    updateScale<Key extends keyof T, Fn extends (tokens: T[Key]) => Record<string | number, unknown>>(key: Key, updateFn: Fn): ThemeBuilder<T & Record<Key, T[Key] & ReturnType<Fn>>>;
+    /**
+     * This finalizes the theme build and returns the final theme and variables to be provided.
+     */
+    build(): T & PrivateThemeKeys;
+}
+export declare function createTheme<T extends AbstractTheme>(base: T): ThemeBuilder<T>;

package/dist/utils/flattenScale.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns an exhaustive list of all possible paths of an object T for keys K.
+ * Possibilities are returned as `k1.k2.k3`.
+ */
+export declare type FindPath<T, K extends keyof T, D extends string = '.'> = K extends string | number ? T[K] extends Record<string | number, any> ? T[K] extends ArrayLike<any> ? K | `${K}${D}${FindPath<T[K], Exclude<keyof T[K], keyof any[]>, D>}` : K | `${K}${D}${FindPath<T[K], keyof T[K], D>}` : K : never;
+/** Returns valid paths of object T */
+export declare type Path<T, D extends string = '.'> = FindPath<T, keyof T, D> | keyof T;
+/** Returns the value of a valid path P `k1.k2.k3` in object T */
+export declare type PathValue<T, P extends Path<T, D>, D extends string = '.'> = P extends `${infer K}${D}${infer Rest}` ? K extends keyof T ? Rest extends Path<T[K], D> ? PathValue<T[K], Rest, D> : never : never : P extends keyof T ? T[P] : never;
+/** Check if path has a primitive end value and return only the union of end paths */
+export declare type PathToLiteral<T, K extends Path<T, D>, D extends string = '.', Base extends string = ''> = PathValue<T, K, D> extends string | number ? K extends string | number ? K extends `${infer BasePath}${D}${Base}` ? BasePath : K : never : never;
+/**
+ * Reduce all paths to a single map of paths with primitive values removing all extra non stateful paths
+ * { path: { sub: 1 } } => { 'path-sub': 1 }
+ *
+ */
+export declare type LiteralPaths<T extends Record<string | number, any>, D extends string = '.', Base extends string = ''> = {
+    [K in Path<T, D> as PathToLiteral<T, K, D, Base>]: PathValue<T, PathToLiteral<T, K, D>, D>;
+};
+export declare function flattenScale<T extends Record<string | number, any>, P extends string>(object: T, path?: P): LiteralPaths<T, '-', '_'>;

package/dist/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './createTheme';
+export * from './serializeTokens';
+export * from './flattenScale';

package/dist/utils/serializeTokens.d.ts

@@ -0,0 +1,18 @@
+import { Theme } from '@emotion/react';
+import { CSSObject } from '@animus-ui/core';
+/**
+ * Returns an type of any object with { key: 'var(--key) }
+ */
+export declare type KeyAsVariable<T extends Record<string, any>, Prefix extends string> = {
+    [V in keyof T]: `var(--${Prefix}-${Extract<V, string>})`;
+};
+declare type SerializedTokensInput = Record<string, string | number | CSSObject | SerializedTokensInputRecursive>;
+interface SerializedTokensInputRecursive {
+    [i: number]: SerializedTokensInput;
+    [i: string]: SerializedTokensInput;
+}
+export declare const serializeTokens: <T extends SerializedTokensInput, Prefix extends string>(tokens: T, prefix: Prefix, theme: Theme | undefined) => {
+    tokens: KeyAsVariable<T, Prefix>;
+    variables: CSSObject;
+};
+export {};

package/dist/utils/types.d.ts

@@ -0,0 +1,41 @@
+import { AbstractTheme, CSSObject } from '@animus-ui/core';
+/**
+ * This is a custom generic that ensures the safety of adding additional values to a theme object without accidentally wiping out
+ * required keys like `breakpoints`.  It works by creating a new mapped type and merging the values of the union of Base & Next:
+ * 1. If the key exists on both Base and Next return the intersection of both values
+ * 2. If the key exists on next use the value on next.
+ * 3. If the key exists on base but nothing else use the value on base.
+ *
+ * The resulting type is then rejoined with keys that cannot be mutated (breakpoints) as the next version of Theme
+ */
+export declare type MergeTheme<Base extends AbstractTheme, Next, Unmergable = Record<'breakpoints', Base['breakpoints']>> = Unmergable & Merge<Base, Next>;
+/** This merges at 2 levels of depth */
+export declare type Merge<A, B> = {
+    [K in keyof (A & B)]: K extends keyof B ? K extends keyof A ? AssignValueIfUnmergable<A[K], B[K]> : B[K] : K extends keyof A ? A[K] : never;
+};
+/** Extract mergable objects */
+export declare type Mergable<T> = Exclude<T, ((...args: any) => any) | string | boolean | symbol | number | any[]>;
+/** Return B if either A or B is unmergable */
+export declare type AssignValueIfUnmergable<A, B> = Mergable<A> extends never ? B : Mergable<B> extends never ? B : Assign<A, B>;
+/** Prefer all values from B */
+export declare type Assign<A, B> = {
+    [K in keyof A | keyof B]: K extends keyof B ? B[K] : K extends keyof A ? A[K] : never;
+};
+/** These are keys that are consistent for all theme builds - they are loosely typed as they are not meant to be accessed directly */
+export declare type PrivateThemeKeys = {
+    _variables: Record<string, CSSObject>;
+    _tokens: Record<string | number, any>;
+};
+/** This allows 3 layers of color aliases to be constructed when adding colorModes
+ * @example
+ * {
+ *   button: {
+ *     bg: {
+ *       hover: 'someAlias'
+ *     }
+ *   }
+ * }
+ *
+ * `button-bg-hover`
+ * */
+export declare type ColorModeConfig<Colors> = Record<string, Colors | Record<string, Colors> | Record<string, Colors | Record<string, Colors>>>;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@animus-ui/theming",
+  "version": "0.0.1-alpha.0+5f19171",
+  "description": "> TODO: description",
+  "author": "Aaron Robb <airrobb@gmail.com>",
+  "homepage": "https://github.com/codecaaron/animus#readme",
+  "license": "MIT",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codecaaron/animus.git"
+  },
+  "scripts": {
+    "build:clean": "rm -rf ./dist",
+    "build": "yarn  build:clean && rollup -c",
+    "lernaBuildTask": "yarn build"
+  },
+  "bugs": {
+    "url": "https://github.com/codecaaron/animus/issues"
+  },
+  "dependencies": {
+    "@animus-ui/core": "^0.0.1-alpha.0+5f19171"
+  },
+  "peerDependencies": {
+    "@emotion/react": ">=11.0.0",
+    "@emotion/styled": ">=11.0.0",
+    "lodash": "*",
+    "typescript": ">=4.3.5"
+  },
+  "gitHead": "5f191713f482153b8dd1948e4d0f9f6b56a2e9fc"
+}

package/rollup.config.js

@@ -0,0 +1,3 @@
+import config from '../../rollup.config';
+
+export default config();

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    // "emitDeclarationOnly": true,
+    "outDir": "./dist"
+  },
+  "include": ["../../typings/*.d.ts", "./src/**/*.ts", "./src/**/*.tsx"],
+  "exclude": ["./**/*.test.tsx", "./**/*.test.ts"]
+}