ember-freestyle 0.16.0-beta.0 → 0.17.0-alpha-css-vars-api.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to this project will be documented in this file.
 
 
 
+
+## v0.17.0-alpha-css-vars-api.0 (2022-10-17)
+
+#### :rocket: Enhancement
+* [#856](https://github.com/chrislopresto/ember-freestyle/pull/856) Make the navigation menu sticky ([@bertdeblock](https://github.com/bertdeblock))
+
+#### Committers: 1
+- Bert De Block ([@bertdeblock](https://github.com/bertdeblock))
+
 ## v0.16.0-beta.0 (2022-09-22)
 
 #### :boom: Breaking Change

package/addon/components/freestyle/usage/basic-css-variable/index.hbs

@@ -0,0 +1,34 @@
+<tr class="FreestyleUsageCssVar">
+  <td class="FreestyleUsageCssVar-name">
+    {{@name}}
+  </td>
+
+  <td class="FreestyleUsageCssVar-description">
+    <span class="FreestyleUsageCssVar-type u-codePill">
+      {{@type}}
+    </span>
+
+    {{@description}}
+  </td>
+
+  <td class="FreestyleUsageCssVar-details">
+    {{#if this.shouldRenderDefaultValue}}
+      <span class="FreestyleUsageCssVar-default u-codePill">
+        {{@defaultValue.raw}}
+      </span>
+      {{#if this.shouldRenderDefaultComputed}}
+        ({{@defaultValue.computed}})
+      {{/if}}
+    {{/if}}
+  </td>
+
+  <td class="FreestyleUsageCssVar-controls FreestyleUsageCssVar-controls--string">
+    {{#unless @hideControls}}
+      <Freestyle::Usage::String::Control
+        @options={{@options}}
+        @value={{@value}}
+        @onInput={{@onInput}}
+      />
+    {{/unless}}
+  </td>
+</tr>

package/addon/components/freestyle/usage/basic-css-variable/index.ts

@@ -0,0 +1,28 @@
+import Component from '@glimmer/component';
+import { type CSSVariableDefaults } from 'ember-freestyle';
+
+interface Signature {
+  Args: {
+    name?: string;
+    description?: string;
+    defaultValue?: CSSVariableDefaults;
+    type?: string;
+    hideControls?: boolean;
+    value?: string;
+    options?: string[];
+    onInput: (val: string | null | undefined) => void;
+  };
+}
+
+export default class FreestyleUsageBasicCssVariableComponent extends Component<Signature> {
+  get shouldRenderDefaultValue(): boolean {
+    return this.args.defaultValue !== undefined;
+  }
+  get shouldRenderDefaultComputed(): boolean {
+    const { defaultValue } = this.args;
+    return (
+      defaultValue?.computed !== undefined &&
+      defaultValue.computed !== defaultValue.raw
+    );
+  }
+}

package/addon/components/freestyle/usage/index.hbs

@@ -56,6 +56,32 @@
       {{/if}}
     {{/if}}
 
+    {{#if (has-block 'cssVars')}}
+      {{#if this.showApi}}
+        <div class="FreestyleUsage-cssVars">
+          <h3 class="FreestyleUsage-cssVarsTitle">CSS Variables API</h3>
+
+          <table class="FreestyleUsage-cssVarsTable">
+            <thead>
+              <tr>
+                <th>Variable</th>
+                <th>Description</th>
+                <th>Default</th>
+                <th>Value</th>
+              </tr>
+            </thead>
+            <tbody>
+              {{yield
+                (hash
+                  Basic=(component 'freestyle/usage/basic-css-variable' )
+                )
+              to="cssVars"}}
+            </tbody>
+          </table>
+        </div>
+      {{/if}}
+    {{/if}}
+
     {{#if this.showSource}}
       <div class="FreestyleUsage-sourceContainer" {{did-insert this.highlightSource}}>
         <FreestyleSource @source={{@source}} />

package/addon/components/freestyle/usage/index.ts

@@ -30,6 +30,11 @@ interface Signature {
         Yield: any;
       }
     ];
+    cssVars: [
+      {
+        Basic: any;
+      }
+    ];
   };
 }
 

package/addon/decorators/css-variable.ts

@@ -0,0 +1,155 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { dasherize } from '@ember/string';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+import {
+  getComputedValueForCssVariable as cssVarComputedValue,
+  getCssVariableDefinition as cssVarAuthoredValue,
+} from 'ember-freestyle/utils/css-rules';
+
+/*
+   This decorator defines a property returning a CssVariableInfo instance.
+
+   The options accepted by the decorator are:
+
+   cssClassName: string;
+   toVariableName: (propertyName: string) => string;
+
+   The toVariableName option is used to converts the property name to a
+   a css variable name. The default implementation of this callback dasherizes
+   the property name to get the css variable name.
+   
+   The default value (both authored and computed) is looked up on the
+   selector specified by options.cssClassName and a CSSVariableInfo is
+   initialized and returned.
+
+   If options.cssClassName is not specified, the decorator will try to read
+   a `cssClassName` property from the object with the decorated property.
+   If this is also not present, an error will be thrown.
+
+   The overloads defined here are needed to handle both the no-args decorator usage
+   as well as the version with parentheses. e.g.
+
+   @cssVariable declare fooColor: CSSVariableInfo;
+   @cssVariable({ cssClassName: 'Foo' }) declare fooColor: CSSVariableInfo;
+ */
+export function cssVariable(target: TargetInstance, key: string): any;
+export function cssVariable(options: Partial<CSSVariableDecoratorOptions>): any;
+export function cssVariable(
+  targetOrOptions: TargetInstance | CSSVariableDecoratorOptions,
+  key?: string
+): any {
+  if (typeof key === 'string') {
+    return {
+      get(): CSSVariableInfo {
+        const options = prepareOptions(this, {});
+        return getCssVariableInfoMemoized(this, key, options);
+      },
+    };
+  } else {
+    return function (_target: TargetInstance, key: string) {
+      return {
+        get(this: TargetInstance): CSSVariableInfo {
+          let options = targetOrOptions as CSSVariableDecoratorOptions;
+          options = prepareOptions(this, options);
+          return getCssVariableInfoMemoized(this, key, options);
+        },
+      };
+    };
+  }
+}
+
+export interface CSSVariableDefaults {
+  raw: string | undefined;
+  computed: string | undefined;
+}
+
+export class CSSVariableInfo {
+  name: string;
+  defaults: CSSVariableDefaults;
+  @tracked value: string | undefined;
+
+  constructor(variableName: string, cssClassName: string) {
+    this.name = variableName;
+
+    let raw = cssVarAuthoredValue(variableName, '.' + cssClassName);
+    raw = raw?.trim() ?? undefined;
+
+    let computed = cssVarComputedValue(variableName, cssClassName);
+    computed = computed?.trim() ?? undefined;
+
+    this.defaults = {
+      raw,
+      computed,
+    };
+    this.value = raw ?? computed;
+  }
+
+  @action
+  update(val: string) {
+    this.value = val;
+  }
+}
+
+// we use a WeakMap in order to allow target instances to be garbage-collected
+const memoizationMap = new WeakMap<
+  TargetInstance,
+  Map<string, CSSVariableInfo>
+>();
+
+interface TargetInstance {
+  constructor: { name: string };
+  cssClassName?: string;
+}
+
+interface CSSVariableDecoratorOptions {
+  toVariableName: (propertyName: string) => string;
+  cssClassName: string; // the CSS class name to use to read the default value of the variable from
+}
+
+function getCssVariableInfoMemoized(
+  target: TargetInstance,
+  key: string,
+  options: CSSVariableDecoratorOptions
+): CSSVariableInfo {
+  if (!memoizationMap.get(target)) {
+    memoizationMap.set(target, new Map());
+  }
+  const memoizedInfos = memoizationMap.get(target);
+  if (memoizedInfos) {
+    let result = memoizedInfos.get(key);
+    if (!result) {
+      const name = options.toVariableName(key);
+      result = new CSSVariableInfo(name, options.cssClassName);
+      memoizedInfos.set(key, result);
+    }
+    return result;
+  } else {
+    throw new Error(
+      'Unexpected missing key in cssVariable decorator implementation'
+    );
+  }
+}
+
+function prepareOptions(
+  targetInstance: TargetInstance,
+  userSpecifiedOptions: Partial<CSSVariableDecoratorOptions>
+): CSSVariableDecoratorOptions {
+  let options = userSpecifiedOptions;
+  if (!options.cssClassName) {
+    const cssClassName = targetInstance['cssClassName'];
+    if (!cssClassName) {
+      throw new Error(
+        'Must specify `cssClassName` as an option to @cssVariable decorator or define `cssClassName` on the class owning the decorated property'
+      );
+    }
+    options = Object.assign({}, options, { cssClassName });
+  }
+  return Object.assign(
+    {
+      toVariableName: dasherize,
+    },
+    options as Pick<CSSVariableDecoratorOptions, 'cssClassName'> &
+      Partial<CSSVariableDecoratorOptions>
+  );
+}

package/addon/glint.ts

@@ -1,6 +1,7 @@
 import type FreestyleUsage from 'ember-freestyle/components/freestyle/usage';
 import type FreestyleUsageArgument from 'ember-freestyle/components/freestyle/usage/argument';
 import type FreestyleUsageArray from 'ember-freestyle/components/freestyle/usage/array';
+import type FreestyleUsageBasicCssVariable from 'ember-freestyle/components/freestyle/usage/basic-css-variable';
 import type FreestyleUsageBool from 'ember-freestyle/components/freestyle/usage/bool';
 import type FreestyleUsageBoolControl from 'ember-freestyle/components/freestyle/usage/bool/control';
 import type FreestyleUsageNumber from 'ember-freestyle/components/freestyle/usage/number';
@@ -40,6 +41,8 @@ declare module '@glint/environment-ember-loose/registry' {
     'freestyle/usage/bool': typeof FreestyleUsageBool;
     'Freestyle::Usage::Bool::Control': typeof FreestyleUsageBoolControl;
     'Freestyle::Usage::Number': typeof FreestyleUsageNumber;
+    'Freestyle::Usage::BasicCssVariable': typeof FreestyleUsageBasicCssVariable;
+    'freestyle/usage/basic-css-variable': typeof FreestyleUsageBasicCssVariable;
     'freestyle/usage/number': typeof FreestyleUsageNumber;
     'Freestyle::Usage::Number::Control': typeof FreestyleUsageNumberControl;
     'Freestyle::Usage::Object': typeof FreestyleUsageObject;

package/addon/index.ts

@@ -0,0 +1,2 @@
+export { cssVariable, CSSVariableInfo } from './decorators/css-variable';
+export type { CSSVariableDefaults } from './decorators/css-variable';

package/addon/utils/css-rules.ts

@@ -0,0 +1,61 @@
+// module-scope variable to cache an array of all our readable CSS rules
+let allRules: CSSRule[] | undefined;
+
+function getReadableCssRules(): CSSRule[] {
+  if (!allRules) {
+    allRules = Array.from(document.styleSheets)
+      .map((ss: CSSStyleSheet) => {
+        try {
+          return ss.cssRules;
+        } catch (e) {
+          // Not all stylesheets allow you to access the rules. The restrictions generally match CORS rules.
+          return null;
+        }
+      })
+      .filter(Boolean)
+      .flatMap((rules: CSSRuleList) => Array.from(rules));
+  }
+  return allRules;
+}
+
+function getStyleDeclarations(selector: string): CSSStyleDeclaration[] {
+  return getReadableCssRules()
+    .filter((rule: CSSStyleRule) => rule.selectorText === selector)
+    .flatMap((rule: CSSStyleRule) => rule.style);
+}
+
+export function getCssVariableDefinition(
+  variableName: string,
+  selector: string
+): string {
+  // find the last declaration of the selector that contains a value
+  // for the CSS variable we're interested in
+  const styleDeclaration = getStyleDeclarations(selector)
+    .filter((sd) => sd.getPropertyValue(`--${variableName}`))
+    .reverse()[0];
+
+  // return the value as defined in this declaration
+  return styleDeclaration?.getPropertyValue(`--${variableName}`);
+}
+
+export function getComputedValueForCssVariable(
+  variableName: string,
+  cssClassName: string
+): string {
+  let element = document.querySelector('.' + cssClassName);
+  let tempElement;
+  if (!element) {
+    // if an element with the specified classname is not present
+    // in the DOM, create a temporary one that we can use to read
+    // the computed property value
+    tempElement = document.createElement('div');
+    tempElement.className = cssClassName;
+    document.body.appendChild(tempElement);
+    element = tempElement;
+  }
+  const result = getComputedStyle(element).getPropertyValue(
+    `--${variableName}`
+  );
+  tempElement?.remove();
+  return result;
+}

package/app/components/freestyle/usage/basic-css-variable.js

@@ -0,0 +1 @@
+export { default } from 'ember-freestyle/components/freestyle/usage/basic-css-variable';

package/app/styles/components/freestyle/usage.scss

@@ -20,7 +20,12 @@
     color: #666;
   }
 
-  &-apiTitle {
+  &-api + &-cssVars {
+    margin-top: 1rem;
+  }
+
+  &-apiTitle,
+  &-cssVarsTitle {
     font-size: 0.9rem;
     font-weight: bold;
     margin: 0;
@@ -53,12 +58,14 @@
   }
 
   &-sourceContainer,
-  &-apiTable {
+  &-apiTable,
+  &-cssVarsTable {
     margin-left: -1rem;
     margin-right: -1rem;
   }
 
-  &-apiTable {
+  &-apiTable,
+  &-cssVarsTable {
     width: 100%;
     padding: 0.5rem 0 0.2rem;
     border-collapse: collapse;
@@ -90,7 +97,8 @@
 /*
   FreestyleUsageArgument
 */
-.FreestyleUsageArgument {
+.FreestyleUsageArgument,
+.FreestyleUsageCssVar {
   font-size: 0.8rem;
 
   &-name {

package/app/styles/components/freestyle-guide.scss

@@ -92,8 +92,12 @@ $FreestyleGuide-boxShadow: 0 2px 5px 0 $FreestyleGuide-shadow1,
 
   &-nav {
     background-color: $FreestyleGuide-color--background;
+    height: 100vh;
     order: -1;
+    overflow: auto;
     padding: 1rem;
+    position: sticky;
+    top: 0;
 
     @include freestyle-breakpoint(large) {
       border-right: solid 1px $FreestyleGuide-color--secondary;

package/components/freestyle/usage/basic-css-variable/index.d.ts

@@ -0,0 +1,19 @@
+import Component from '@glimmer/component';
+import { type CSSVariableDefaults } from 'ember-freestyle';
+interface Signature {
+    Args: {
+        name?: string;
+        description?: string;
+        defaultValue?: CSSVariableDefaults;
+        type?: string;
+        hideControls?: boolean;
+        value?: string;
+        options?: string[];
+        onInput: (val: string | null | undefined) => void;
+    };
+}
+export default class FreestyleUsageBasicCssVariableComponent extends Component<Signature> {
+    get shouldRenderDefaultValue(): boolean;
+    get shouldRenderDefaultComputed(): boolean;
+}
+export {};

package/components/freestyle/usage/index.d.ts

@@ -24,6 +24,11 @@ interface Signature {
                 Yield: any;
             }
         ];
+        cssVars: [
+            {
+                Basic: any;
+            }
+        ];
     };
 }
 export default class extends Component<Signature> {

package/decorators/css-variable.d.ts

@@ -0,0 +1,24 @@
+export declare function cssVariable(target: TargetInstance, key: string): any;
+export declare function cssVariable(options: Partial<CSSVariableDecoratorOptions>): any;
+export interface CSSVariableDefaults {
+    raw: string | undefined;
+    computed: string | undefined;
+}
+export declare class CSSVariableInfo {
+    name: string;
+    defaults: CSSVariableDefaults;
+    value: string | undefined;
+    constructor(variableName: string, cssClassName: string);
+    update(val: string): void;
+}
+interface TargetInstance {
+    constructor: {
+        name: string;
+    };
+    cssClassName?: string;
+}
+interface CSSVariableDecoratorOptions {
+    toVariableName: (propertyName: string) => string;
+    cssClassName: string;
+}
+export {};

package/glint.d.ts

@@ -1,6 +1,7 @@
 import type FreestyleUsage from 'ember-freestyle/components/freestyle/usage';
 import type FreestyleUsageArgument from 'ember-freestyle/components/freestyle/usage/argument';
 import type FreestyleUsageArray from 'ember-freestyle/components/freestyle/usage/array';
+import type FreestyleUsageBasicCssVariable from 'ember-freestyle/components/freestyle/usage/basic-css-variable';
 import type FreestyleUsageBool from 'ember-freestyle/components/freestyle/usage/bool';
 import type FreestyleUsageBoolControl from 'ember-freestyle/components/freestyle/usage/bool/control';
 import type FreestyleUsageNumber from 'ember-freestyle/components/freestyle/usage/number';
@@ -39,6 +40,8 @@ declare module '@glint/environment-ember-loose/registry' {
         'freestyle/usage/bool': typeof FreestyleUsageBool;
         'Freestyle::Usage::Bool::Control': typeof FreestyleUsageBoolControl;
         'Freestyle::Usage::Number': typeof FreestyleUsageNumber;
+        'Freestyle::Usage::BasicCssVariable': typeof FreestyleUsageBasicCssVariable;
+        'freestyle/usage/basic-css-variable': typeof FreestyleUsageBasicCssVariable;
         'freestyle/usage/number': typeof FreestyleUsageNumber;
         'Freestyle::Usage::Number::Control': typeof FreestyleUsageNumberControl;
         'Freestyle::Usage::Object': typeof FreestyleUsageObject;

package/index.d.ts

@@ -0,0 +1,2 @@
+export { cssVariable, CSSVariableInfo } from './decorators/css-variable';
+export type { CSSVariableDefaults } from './decorators/css-variable';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-freestyle",
-  "version": "0.16.0-beta.0",
+  "version": "0.17.0-alpha-css-vars-api.0",
   "description": "Create a living styleguide for your Ember app.",
   "keywords": [
     "ember-addon"
@@ -97,6 +97,7 @@
     "ember-cli-inject-live-reload": "^2.1.0",
     "ember-cli-sass": "^11.0.1",
     "ember-cli-sri": "^2.1.1",
+    "ember-cli-string-helpers": "^6.1.0",
     "ember-cli-terser": "^4.0.2",
     "ember-cli-typescript-blueprints": "^3.0.0",
     "ember-code-snippet": "^3.0.0",
@@ -106,6 +107,7 @@
     "ember-resolver": "^8.0.3",
     "ember-source": "~4.7.0",
     "ember-source-channel-url": "^3.0.0",
+    "ember-style-modifier": "^0.8.0",
     "ember-template-imports": "^3.1.1",
     "ember-template-lint": "^4.14.0",
     "ember-try": "^2.0.0",

package/types/global.d.ts

@@ -3,7 +3,8 @@ import '@glint/environment-ember-loose';
 import AndHelper from 'ember-truth-helpers/helpers/and';
 import EqHelper from 'ember-truth-helpers/helpers/eq';
 import NotHelper from 'ember-truth-helpers/helpers/not';
-import { ModifierLike } from '@glint/template';
+import { HelperLike, ModifierLike } from '@glint/template';
+import { SafeString } from '@ember/template/-private/handlebars';
 
 declare module '@glint/environment-ember-loose/registry' {
   export default interface Registry {
@@ -15,5 +16,9 @@ declare module '@glint/environment-ember-loose/registry' {
     }>;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     'focus-trap': ModifierLike<{ Args: { Named: any } }>;
+    'html-safe': HelperLike<{
+      Args: { Positional: [string] };
+      Return: SafeString;
+    }>;
   }
 }

package/utils/css-rules.d.ts

@@ -0,0 +1,2 @@
+export declare function getCssVariableDefinition(variableName: string, selector: string): string;
+export declare function getComputedValueForCssVariable(variableName: string, cssClassName: string): string;

package/vendor/ember-freestyle.css

@@ -69,8 +69,12 @@
 }
 .FreestyleGuide-nav {
   background-color: #fff;
+  height: 100vh;
   order: -1;
+  overflow: auto;
   padding: 1rem;
+  position: sticky;
+  top: 0;
 }
 @media (min-width: 600px) {
   .FreestyleGuide-nav {
@@ -383,7 +387,10 @@ END-FREESTYLE-USAGE */
   font-size: 1.1rem;
   color: #666;
 }
-.FreestyleUsage-apiTitle {
+.FreestyleUsage-api + .FreestyleUsage-cssVars {
+  margin-top: 1rem;
+}
+.FreestyleUsage-apiTitle, .FreestyleUsage-cssVarsTitle {
   font-size: 0.9rem;
   font-weight: bold;
   margin: 0;
@@ -411,30 +418,31 @@ END-FREESTYLE-USAGE */
   display: block;
   border-radius: 0 0 0 var(--radius);
 }
-.FreestyleUsage-sourceContainer, .FreestyleUsage-apiTable {
+.FreestyleUsage-sourceContainer, .FreestyleUsage-apiTable, .FreestyleUsage-cssVarsTable {
   margin-left: -1rem;
   margin-right: -1rem;
 }
-.FreestyleUsage-apiTable {
+.FreestyleUsage-apiTable, .FreestyleUsage-cssVarsTable {
   width: 100%;
   padding: 0.5rem 0 0.2rem;
   border-collapse: collapse;
 }
-.FreestyleUsage-apiTable th {
+.FreestyleUsage-apiTable th, .FreestyleUsage-cssVarsTable th {
   text-align: left;
   font-size: 0.8rem;
   font-weight: 600;
   color: #777;
 }
-.FreestyleUsage-apiTable tr {
+.FreestyleUsage-apiTable tr, .FreestyleUsage-cssVarsTable tr {
   border-bottom: 1px solid var(--border-color);
   vertical-align: top;
 }
-.FreestyleUsage-apiTable tr:nth-child(even) {
+.FreestyleUsage-apiTable tr:nth-child(even), .FreestyleUsage-cssVarsTable tr:nth-child(even) {
   background-color: #f9f9f9;
 }
 .FreestyleUsage-apiTable th,
-.FreestyleUsage-apiTable td {
+.FreestyleUsage-apiTable td, .FreestyleUsage-cssVarsTable th,
+.FreestyleUsage-cssVarsTable td {
   padding: 0.5rem 1rem;
 }
 .FreestyleUsage-sourceContainer {
@@ -444,24 +452,30 @@ END-FREESTYLE-USAGE */
 /*
   FreestyleUsageArgument
 */
-.FreestyleUsageArgument {
+.FreestyleUsageArgument,
+.FreestyleUsageCssVar {
   font-size: 0.8rem;
 }
-.FreestyleUsageArgument-name {
+.FreestyleUsageArgument-name,
+.FreestyleUsageCssVar-name {
   font-weight: bold;
   width: 20%;
 }
-.FreestyleUsageArgument-description {
+.FreestyleUsageArgument-description,
+.FreestyleUsageCssVar-description {
   width: 40%;
 }
-.FreestyleUsageArgument-required {
+.FreestyleUsageArgument-required,
+.FreestyleUsageCssVar-required {
   color: #d81c38;
   font-style: oblique;
 }
-.FreestyleUsageArgument-default {
+.FreestyleUsageArgument-default,
+.FreestyleUsageCssVar-default {
   font-family: monospace;
 }
-.FreestyleUsageArgument-jsonViewer {
+.FreestyleUsageArgument-jsonViewer,
+.FreestyleUsageCssVar-jsonViewer {
   background-color: #222;
   min-width: 300px;
   padding: 1rem;