@blockquote-web-components/blockquote-base-style-helpers 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 blockquote-base-style-helpers
+
+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.js

@@ -0,0 +1,103 @@
+/**
+![Lit](https://img.shields.io/badge/lit-2.0.0-blue)
+
+`BlockquoteBaseStyleHelpers` offers a set of helper functions for working with CSS.
+
+There are two kinds of helps:
+
+- Shared styles between components
+- Document-level styles
+
+## Shared styles between components
+
+[Adaptation of the Polymer ideas so that components can share styles, using native JS modules](https://polymer-library.polymer-project.org/2.0/docs/devguide/style-shadow-dom#share-styles-between-elements)
+
+Using the shared styles is a two-step process:
+
+- setComponentSharedStyles
+- getComponentSharedStyles
+
+### setComponentSharedStyles
+
+Define a shared-style inside a JS module.
+
+The id attribute specifies the name you'll use to reference your shared styles, multiple shared styles can be registered using the same ID.
+These will be applied to the component in the order they were registered.
+
+__shared-styles__
+
+```js
+import { css } from 'lit';
+import { setComponentSharedStyles } from blockquote-base-style-helpers.js;
+
+setComponentSharedStyles('x-foo-shared-styles', css`
+ :host {
+   background-color: red;
+ }
+ p {
+   color: blue;
+ }
+`);
+```
+
+### getComponentSharedStyles
+
+A component can use `getComponentSharedStyles` for retrieving style blocks and add it to its local styles extending or overriding it.
+
+__Component__
+
+```js
+import { LitElement, html, css } from 'lit';
+import { getComponentSharedStyles } from 'blockquote-base-style-helpers';
+
+class XFoo extends LitElement {
+ static get styles() {
+   return [
+     css`...`,
+     getComponentSharedStyles('x-foo-shared-styles)
+   ];
+ }
+}
+```
+
+## Document-level styles
+
+[Adaptation of the Polymer ideas so for defining styles in the main document](https://polymer-library.polymer-project.org/2.0/docs/devguide/style-shadow-dom#custom-style)
+
+### Progressive Enhancement:
+
+- support browsers without native `Shadow DOM`
+- support browsers with native `Shadow DOM` but without `adoptedStyleSheets`
+- support browsers with native `Shadow DOM` and `adoptedStyleSheets`
+
+#### support browsers without native `Shadow DOM`
+
+The responsibility is delegated to:
+
+- [custom-style](https://polymer-library.polymer-project.org/2.0/docs/devguide/style-shadow-dom#custom-style)
+  - [customstyleinterface](https://github.com/webcomponents/polyfills/tree/master/packages/shadycss#about-customstyleinterface)
+
+#### **support browsers with native `Shadow DOM`**
+
+The responsibility is delegated to:
+
+- [Lit - adoptedStyleSheets](https://github.com/lit/lit/blob/main/packages/reactive-element/src/css-tag.ts#L160)
+
+```js
+import { css } from 'lit';
+import { setDocumentCustomStyles } from 'document-styles';
+
+setDocumentCustomStyles(css`
+  :root {
+    --bg-color: rgba(0, 0, 255, 0.5);
+  }
+  p {
+    background-color: rgba(255, 0, 0, 0.5);
+    padding: 0.25rem 0.5rem;
+  }
+`);
+```
+@tagname blockquote-base-style-helpers
+@element blockquote-base-style-helpers
+*/
+export class ReadmElement extends HTMLElement {}

package/README.md

@@ -0,0 +1,100 @@
+# blockquote-base-style-helpers
+
+![Lit](https://img.shields.io/badge/lit-2.0.0-blue)
+
+`BlockquoteBaseStyleHelpers` offers a set of helper functions for working with CSS.
+
+There are two kinds of helps:
+
+- Shared styles between components
+- Document-level styles
+
+## Shared styles between components
+
+[Adaptation of the Polymer ideas so that components can share styles, using native JS modules](https://polymer-library.polymer-project.org/2.0/docs/devguide/style-shadow-dom#share-styles-between-elements)
+
+Using the shared styles is a two-step process:
+
+- setComponentSharedStyles
+- getComponentSharedStyles
+
+### setComponentSharedStyles
+
+Define a shared-style inside a JS module.
+
+The id attribute specifies the name you'll use to reference your shared styles, multiple shared styles can be registered using the same ID.
+These will be applied to the component in the order they were registered.
+
+__shared-styles__
+
+```js
+import { css } from 'lit';
+import { setComponentSharedStyles } from blockquote-base-style-helpers.js;
+
+setComponentSharedStyles('x-foo-shared-styles', css`
+:host {
+  background-color: red;
+}
+p {
+  color: blue;
+}
+`);
+```
+
+### getComponentSharedStyles
+
+A component can use `getComponentSharedStyles` for retrieving style blocks and add it to its local styles extending or overriding it.
+
+__Component__
+
+```js
+import { LitElement, html, css } from 'lit';
+import { getComponentSharedStyles } from 'blockquote-base-style-helpers';
+
+class XFoo extends LitElement {
+static get styles() {
+  return [
+    css`...`,
+    getComponentSharedStyles('x-foo-shared-styles)
+  ];
+}
+}
+```
+
+## Document-level styles
+
+[Adaptation of the Polymer ideas so for defining styles in the main document](https://polymer-library.polymer-project.org/2.0/docs/devguide/style-shadow-dom#custom-style)
+
+### Progressive Enhancement:
+
+- support browsers without native `Shadow DOM`
+- support browsers with native `Shadow DOM` but without `adoptedStyleSheets`
+- support browsers with native `Shadow DOM` and `adoptedStyleSheets`
+
+#### support browsers without native `Shadow DOM`
+
+The responsibility is delegated to:
+
+- [custom-style](https://polymer-library.polymer-project.org/2.0/docs/devguide/style-shadow-dom#custom-style)
+ - [customstyleinterface](https://github.com/webcomponents/polyfills/tree/master/packages/shadycss#about-customstyleinterface)
+
+#### **support browsers with native `Shadow DOM`**
+
+The responsibility is delegated to:
+
+- [Lit - adoptedStyleSheets](https://github.com/lit/lit/blob/main/packages/reactive-element/src/css-tag.ts#L160)
+
+```js
+import { css } from 'lit';
+import { setDocumentCustomStyles } from 'document-styles';
+
+setDocumentCustomStyles(css`
+ :root {
+   --bg-color: rgba(0, 0, 255, 0.5);
+ }
+ p {
+   background-color: rgba(255, 0, 0, 0.5);
+   padding: 0.25rem 0.5rem;
+ }
+`);
+```

package/index.js

@@ -0,0 +1,9 @@
+export {
+  setDocumentStyles,
+  supportCustomStyleInterface,
+  supportsAdoptingStyleSheets,
+  documentAdoptStyles,
+} from './src/setDocumentStyles.js';
+
+export { setComponentSharedStyles } from './src/setComponentSharedStyles.js';
+export { getComponentSharedStyles } from './src/getComponentSharedStyles.js';

package/package.json

@@ -0,0 +1,140 @@
+{
+  "name": "@blockquote-web-components/blockquote-base-style-helpers",
+  "version": "1.0.0",
+  "description": "Webcomponent blockquote-base-style-helpers following open-wc recommendations",
+  "keywords": [
+    "lit",
+    "web-component",
+    "lit-element"
+  ],
+  "license": "MIT",
+  "author": "blockquote-base-style-helpers",
+  "main": "index.js",
+  "module": "index.js",
+  "files": [
+    "/define/",
+    "/src/",
+    "index.js",
+    "!/**/*.scss"
+  ],
+  "scripts": {
+    "analyze": "cem analyze --litelement --globs \"{src,define}/**/*.{js,ts}\" \"index.js\"",
+    "analyze:doc": "npm run analyze && npx web-component-analyzer \"{src,define}/**/*.{js,ts}\" \"index.js\" \"README.js\" --outFile README.md",
+    "build": "echo \"This is not a TypeScript project, so no need to build.\"",
+    "dev:vite": "vite build",
+    "format": "npm run format:eslint && npm run format:prettier && npm run format:stylelint",
+    "format:eslint": "eslint \"**/*.{js,ts,html}\" --fix --ignore-path .eslintignore",
+    "format:prettier": "prettier \"**/*.{js,ts,json,html}\" --write --ignore-path .eslintignore",
+    "format:stylelint": "stylelint \"**/*.{scss,css}\" --fix --allow-empty-input --ignore-path .eslintignore",
+    "postinstall": "npm run sort:package",
+    "lint": "npm run lint:eslint && npm run lint:prettier && npm run lint:stylelint",
+    "lint:eslint": "eslint \"**/*.{js,ts,html}\" --ignore-path .eslintignore",
+    "lint:prettier": "prettier \"**/*.{js,ts,json,html}\" --check --ignore-path .eslintignore",
+    "lint:stylelint": "stylelint \"**/*.{scss,css}\" --allow-empty-input --ignore-path .eslintignore",
+    "preview:vite": "vite preview",
+    "sass:watch": "sass-style-template",
+    "sort:package": "npx sort-package-json",
+    "start": "concurrently -k -r \"npm:sass:watch\" \"npm:vite\"",
+    "start:wds": "concurrently -k -r \"npm:sass:watch\" \"npm:wds\"",
+    "test": "wtr --coverage",
+    "test:watch": "wtr --watch",
+    "vite": "vite",
+    "wds": "web-dev-server"
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "**/*.{js,ts,html}": [
+      "npm run format:eslint"
+    ],
+    "**/*.{js,ts,json,html}": [
+      "npm run format:prettier"
+    ],
+    "**/*.{scss,css}": [
+      "npm run format:stylelint"
+    ]
+  },
+  "prettier": {
+    "arrowParens": "avoid",
+    "printWidth": 100,
+    "singleQuote": true,
+    "trailingComma": "all",
+    "overrides": [
+      {
+        "files": "*.{scss,css}",
+        "options": {
+          "printWidth": 280,
+          "singleQuote": false
+        }
+      }
+    ]
+  },
+  "eslintConfig": {
+    "parserOptions": {
+      "ecmaVersion": "latest"
+    },
+    "plugins": [
+      "log-filenames"
+    ],
+    "extends": [
+      "@open-wc",
+      "prettier"
+    ],
+    "rules": {
+      "class-methods-use-this": "off",
+      "no-unused-expressions": [
+        "error",
+        {
+          "allowShortCircuit": true,
+          "allowTernary": true
+        }
+      ],
+      "object-curly-newline": "off",
+      "import/extensions": [
+        "error",
+        "always",
+        {
+          "ignorePackages": true
+        }
+      ],
+      "import/no-extraneous-dependencies": [
+        "error",
+        {
+          "devDependencies": [
+            "**/test/**/*.{js,ts}",
+            "**/*.config.{js,ts,mjs,cjs}",
+            "**/*.conf.{js,ts,mjs,cjs}"
+          ]
+        }
+      ],
+      "import/no-unresolved": "off",
+      "import/prefer-default-export": "off"
+    }
+  },
+  "stylelint": {
+    "extends": "stylelint-config-standard-scss",
+    "rules": {
+      "custom-property-pattern": null,
+      "max-line-length": null,
+      "no-duplicate-selectors": null,
+      "color-function-notation": null,
+      "alpha-value-notation": null
+    }
+  },
+  "dependencies": {
+    "@blockquote-web-components/blockquote-base-meta": "^1.0.5",
+    "@blockquote/polymer": "^3.4.1",
+    "lit": "^2.0.2"
+  },
+  "devDependencies": {
+    "@blockquote-web-components/blockquote-base-common-dev-dependencies": "^1.2.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "customElements": "custom-elements.json",
+  "gitHead": "f0d88eaef7c6b48711470dd2ff5c7c3eb554e0ec"
+}

package/src/getComponentSharedStyles.js

@@ -0,0 +1,23 @@
+import { css, unsafeCSS } from 'lit';
+import { BlockquoteBaseMeta } from '@blockquote-web-components/blockquote-base-meta';
+
+const meta = new BlockquoteBaseMeta({
+  type: 'sharedStyles',
+});
+
+/**
+ * Get styles (as cssResult) already associated to provided ID string (using setComponentSharedStyles helper) and returns them
+ * @param {String} id Identifier of styles; usually will be `[component-name]-shared-styles`
+ * @returns CSSResult
+ */
+export const getComponentSharedStyles = id => {
+  const sharedStyles = meta.byKey(id);
+  if (sharedStyles) {
+    const onlyCSSResult = sharedStyles.filter(cssResultObject => cssResultObject.cssText);
+    const onlyUnsafeCssResult = unsafeCSS(onlyCSSResult.join(''));
+    return css`
+      ${onlyUnsafeCssResult}
+    `;
+  }
+  return css``;
+};

package/src/setComponentSharedStyles.js

@@ -0,0 +1,21 @@
+import { BlockquoteBaseMeta } from '@blockquote-web-components/blockquote-base-meta';
+
+/**
+ * Set styles (as cssResult) associated to provided ID string which can then be retrieved by components
+ * @param {String} id Identifier of styles; usually will be `[component-name]-shared-styles`
+ * @param {CSSResult} styles Styles to add, wrapper in a Lit css tagged template literal
+ */
+export const setComponentSharedStyles = (id, styles) => {
+  /* c8 ignore if */
+  if (!styles.cssText) {
+    throw new Error(
+      `Value passed to 'setComponentSharedStyles' function must be a 'css' function result`,
+    );
+  }
+  const meta = new BlockquoteBaseMeta({
+    type: 'sharedStyles',
+    key: id,
+  });
+  meta.value = meta.value || [];
+  meta.value.push(styles);
+};

package/src/setDocumentStyles.js

@@ -0,0 +1,45 @@
+import { supportsAdoptingStyleSheets /* adoptStyles */ } from 'lit';
+import '@blockquote/polymer/lib/elements/custom-style.js';
+
+export { supportsAdoptingStyleSheets /* adoptStyles */ } from 'lit';
+export const supportCustomStyleInterface =
+  window.ShadyCSS && /* c8 ignore next */ window.ShadyCSS.CustomStyleInterface;
+
+const renderDocumentRoot = supportsAdoptingStyleSheets
+  ? document
+  : /* c8 ignore next */ document.head;
+
+export const documentAdoptStyles = (renderRoot, styles) => {
+  if (supportsAdoptingStyleSheets) {
+    // eslint-disable-next-line no-param-reassign
+    renderRoot.adoptedStyleSheets = renderRoot.adoptedStyleSheets.concat(
+      styles.map(s => (s instanceof CSSStyleSheet ? s : s.styleSheet)),
+    ); /* TODO PR css-tag.ts */
+  } else {
+    styles.forEach(s => {
+      const style = document.createElement('style');
+      // eslint-disable-next-line dot-notation
+      const nonce = window['litNonce']; /* original css-tag.ts const nonce = global['litNonce'] */
+      if (nonce !== undefined) {
+        style.setAttribute('nonce', nonce);
+      }
+      style.textContent = s.cssText;
+      renderRoot.appendChild(style);
+    });
+  }
+};
+
+const documentCustomStyle = s => {
+  const customStyle = document.createElement('custom-style');
+  const style = document.createElement('style');
+  style.textContent = s.cssText;
+  customStyle.appendChild(style);
+  document.head.appendChild(customStyle);
+  return customStyle;
+};
+
+export const setDocumentStyles = styles => {
+  supportCustomStyleInterface
+    ? documentCustomStyle(styles)
+    : documentAdoptStyles(renderDocumentRoot, [styles]);
+};