@capsizecss/core - npm Package Compare versions

Comparing version 0.0.0-createfontstack-20221110224822 to 0.0.0-master-20240214212615

package.json

 {
   "name": "@capsizecss/core",
-  "version": "0.0.0-createfontstack-20221110224822",
+  "version": "0.0.0-master-20240214212615",
   "description": "Flipping how we define typography",
-  "main": "dist/capsizecss-core.cjs.js",
-  "module": "dist/capsizecss-core.esm.js",
-  "browser": {
-    "./dist/capsizecss-core.cjs.js": "./dist/capsizecss-core.browser.cjs.js",
-    "./dist/capsizecss-core.esm.js": "./dist/capsizecss-core.browser.esm.js"
-  },
-  "preconstruct": {
-    "entrypoints": [
-      "index.ts"
-    ]
-  },
-  "files": [
-    "/dist"
-  ],
-  "author": {
-    "name": "Michael Taranto",
-    "homepage": "https://github.com/michaeltaranto"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/seek-oss/capsize.git",
-    "directory": "packages/core"
-  },
   "keywords": [
@@ -37,11 +14,49 @@ "capsize",
     "line gap",
-    "leading"
+    "leading",
+    "fallback font",
+    "font metrics",
+    "ascent override",
+    "descent override",
+    "line gap override",
+    "size adjust",
+    "content layout shift",
+    "cls"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/seek-oss/capsize.git",
+    "directory": "packages/core"
+  },
   "license": "MIT",
-  "dependencies": {},
+  "author": {
+    "name": "Michael Taranto",
+    "homepage": "https://github.com/michaeltaranto"
+  },
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.ts"
+      },
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "csstype": "^3.1.1"
+  },
   "devDependencies": {
-    "@capsizecss/unpack": "0.0.0-createfontstack-20221110224822",
-    "@emotion/css": "^11.1.3",
-    "csstype": "^3.1.1"
+    "@emotion/css": "^11.11.2"
+  },
+  "scripts": {
+    "build": "crackle package",
+    "dev": "crackle dev --shim=none"
   }
-}
+}

README.md

@@ -1,2 +0,3 @@
-<img src="https://raw.githubusercontent.com/seek-oss/capsize/HEAD/images/capsize-header.png" alt="Capsize" title="Capsize" width="443px" />
+<img src="https://raw.githubusercontent.com/seek-oss/capsize/HEAD/images/capsize-header.png#gh-light-mode-only" alt="Capsize" title="Capsize" width="443px" />
+<img src="https://raw.githubusercontent.com/seek-oss/capsize/HEAD/images/capsize-header-inverted.png#gh-dark-mode-only" alt="Capsize" title="Capsize" width="443px" />
 <br/>
@@ -21,4 +22,9 @@
   - [createFontStack](#createfontstack)
+    - [Usage in CSS stylesheet](#usage-in-css-stylesheet-or-a-style-tag)
+    - [Usage with CSS-in-JS frameworks](#usage-with-css-in-js-frameworks)
+    - [Additional `font-face` properties](#providing-additional-font-face-properties)
   - [precomputeValues](#precomputevalues)
   - [getCapHeight](#getcapheight)
+- [Metrics](#metrics)
+- [Unpack](#unpack)
 - [Integrations](#integrations)
@@ -79,2 +85,4 @@ - [vanilla-extract](packages/vanilla-extract/README.md)
 
+> ⚠️ Note: It is not recommended to apply further layout-related styles to the same element, as this will risk interfering with the styles used for the trim. Instead consider using a nested element.
+
 ### `createStyleString`
@@ -110,2 +118,4 @@
 
+> ⚠️ Note: It is not recommended to apply further layout-related styles to the same element, as this will risk interfering with the styles used for the trim. Instead consider using a nested element.
+
 ## Options
@@ -169,35 +179,140 @@
 
-The core package also provides a few other metrics-based features for improving typography:
+The core package also provides a few other metrics-based features for improving typography on the web:
 
 ### createFontStack
 
-Creates metrics-based [font aliases](https://www.zachleat.com/web/rename-font/) for improved alignment of font family fallbacks.
+Creates metrics-based `@font-face` declarations to improve the alignment of font family fallbacks, which can dramatically improve the [Cumulative Layout Shift](https://web.dev/cls/) metric for sites that depend on a web font.
 
-Generates a `@font-face` definition per fallback font, using font metric overrides that better align the fallback to the preferred font.
+#### Usage
 
-Also returns the generated `fontFamily` with the appropriately ordered font aliases.
+Consider the following example, where the desired web font is [Lobster](https://fonts.google.com/specimen/Lobster), falling back to `Helvetica Neue` and then `Arial`, e.g. `font-family: Lobster, 'Helvetica Neue', Arial`.
 
+1. Import `createFontStack` from the core package:
+
 ```ts
 import { createFontStack } from '@capsizecss/core';
+```
+
+2. Import the font metrics for each of the desired fonts (see [Font Metrics](#font-metrics) above):
+
+```ts
 import lobster from '@capsizecss/metrics/lobster';
+import helveticaNeue from '@capsizecss/metrics/helveticaNeue';
 import arial from '@capsizecss/metrics/arial';
-import helvetica from '@capsizecss/metrics/helvetica';
+```
 
-const fontStack = createFontStack([lobster, helvetica, arial]);
+3. Create your font stack passing the metrics as an array, using the same order as you would via the `font-family` CSS property.
 
-// => {
-//   fontFamily: 'Lobster, "Lobster Fallback: Helvetica", "Lobster Fallback: Arial"',
-//   fontFaces: [
-//     '@font-face': {
-//        fontFamily: '"Lobster Fallback: Helvetica"',
-//        src: 'local("Helvetica")',
-//        'ascent-override': '...%',
-//        'descent-override': '...%',
-//        'line-gap-override': '...%',
-//      },
-//      ...
-//   ]
-// }
+```ts
+const { fontFamily, fontFaces } = createFontStack([
+  lobster,
+  helveticaNeue,
+  arial,
+]);
 ```
 
+The returned value contains the generated font face declarations as well as the computed `fontFamily` with the appropriately ordered font aliases.
+
+#### Usage in CSS stylesheet or a style tag
+
+The returned values can be templated into a stylesheet or a `style` block. Here is an example [handlebars](https://handlebarsjs.com/) template:
+
+```html
+<style type="text/css">
+  .heading {
+    font-family: {{ fontFamily }}
+  }
+
+  {{ fontFaces }}
+</style>
+```
+
+This will produce the following CSS:
+
+```css
+.heading {
+  font-family: Lobster, 'Lobster Fallback: Helvetica Neue',
+    'Lobster Fallback: Arial', 'Helvetica Neue', Arial;
+}
+
+@font-face {
+  font-family: 'Lobster Fallback: Helvetica Neue';
+  src: local('Helvetica Neue');
+  ascent-override: 115.1741%;
+  descent-override: 28.7935%;
+  size-adjust: 86.8251%;
+}
+@font-face {
+  font-family: 'Lobster Fallback: Arial';
+  src: local('Arial');
+  ascent-override: 113.5679%;
+  descent-override: 28.392%;
+  size-adjust: 88.053%;
+}
+```
+
+#### Usage with CSS-in-JS frameworks
+
+If working with a CSS-in-JS library, the returned `fontFaces` can be provided as a JavaScript style object by providing `styleObject` as a `fontFaceFormat` option.
+
+Here is an example using [Emotion](https://emotion.sh/):
+
+```tsx
+import { Global } from '@emotion/core';
+
+const { fontFaces, fontFamily } = createFontStack(
+  [lobster, helveticaNeue, arial],
+  {
+    fontFaceFormat: 'styleObject',
+  },
+);
+
+export const App = () => (
+  <>
+    <Global styles={fontFaces} />
+    <p css={{ fontFamily }}>...</p>
+  </>
+);
+```
+
+> Also useful as a source for further manipulation given it is a data structure that can be iterated over or extended.
+
+#### Providing additional `font-face` properties
+
+Additional properties can be added to the generated `@font-face` declarations via the `fontFaceProperties` option:
+
+```ts
+const { fontFamily, fontFaces } = createFontStack(
+  [lobster, helveticaNeue, arial],
+  {
+    fontFaceProperties: {
+      fontDisplay: 'swap',
+    },
+  },
+);
+```
+
+This will result in the following additions to the declarations:
+
+```diff
+ @font-face {
+   font-family: 'Lobster Fallback: Helvetica Neue';
+   src: local('Helvetica Neue');
+   ascent-override: 115.1741%;
+   descent-override: 28.7935%;
+   size-adjust: 86.8251%;
++  font-display: swap;
+ }
+ @font-face {
+   font-family: 'Lobster Fallback: Arial';
+   src: local('Arial');
+   ascent-override: 113.5679%;
+   descent-override: 28.392%;
+   size-adjust: 88.053%;
++  font-display: swap;
+ }
+```
+
+Worth noting, passing any of the metric override CSS properties will be ignored as they are calculated by Capsize. However, the `size-adjust` property is accepted to support fine-tuning the override for particular use cases. This can be used to finesse the adjustment for specific text, or to disable the adjustment by setting it to `100%`.
+
 ### precomputeValues
@@ -207,3 +322,3 @@
 
-Accepts the same [options](#options) as [createStyleObject][#createstyleobject] and [createStyleString][#createstylestring].
+Accepts the same [options](#options) as [createStyleObject](#createstyleobject) and [createStyleString](#createstylestring).
 
@@ -244,2 +359,22 @@ ```ts
 
+## Metrics
+
+To make the retrieval of font metrics easy, Capsize provides the `@capsizecss/metrics` package containing all the required data for both system and Google fonts.
+
+```bash
+npm install @capsizecss/metrics
+```
+
+See the [package](packages/metrics/README.md) for documentation.
+
+## Unpack
+
+If you are using a custom font or one not included in the `@capsizecss/metrics` package, Capsize provides the `@capsizecss/unpack` package to extract the required data either via a URL or from a local file.
+
+```bash
+npm install @capsizecss/unpack
+```
+
+See the [package](packages/unpack/README.md) for documentation.
+
 ## Integrations
@@ -246,0 +381,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Dev dependency count

1

decreased by-66.67%

Number of lines in readme file

387

increased by53.57%

Number of low supply chain risk alerts

0

decreased by-100%

Worsened metrics

Total package byte prevSize

39114

decreased by-40.8%

Dependency count

1

increased byInfinity%

Number of package files

7

decreased by-61.11%

Lines of code

545

decreased by-66.58%

Number of medium supply chain risk alerts

1

increased byInfinity%

Dependency changes

• + Addedcsstype@^3.1.1

• + Addedcsstype@3.1.3(transitive)