Merge pull request #2 from johnchourajr/feat/aliases

feat: disable defaults, className aliases
johnchourajr · Jun 5, 2024 · c27f8a1 · c27f8a1
2 parents decdcee + 5648c56
commit c27f8a1
Show file tree

Hide file tree

Showing 7 changed files with 164 additions and 51 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,10 @@ A utility library for managing typographic scales in Tailwind CSS.
   - [Type Properties](#type-properties)
     - [Clamp Property](#clamp-property)
   - [Custom Style Keys](#custom-style-keys)
+  - [Custom Aliases for Styles](#custom-aliases-for-styles)
+  - [Disable default type styles](#disable-default-type-styles)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ## Installation
 
@@ -143,15 +147,27 @@ The [default styles](https://github.com/johnchourajr/buen-type/blob/main/src/def
 
 ## Type Properties
 
-| Property        | Type               | Description                                                  |
-| --------------- | ------------------ | ------------------------------------------------------------ |
-| `fontFamily`    | `string`           | The font family to be applied.                               |
-| `fontWeight`    | `string \| number` | The weight of the font.                                      |
-| `lineHeight`    | `string \| number` | The height of the line.                                      |
-| `letterSpacing` | `string`           | The spacing between letters.                                 |
-| `textTransform` | `string`           | The transformation applied to the text (e.g., uppercase).    |
-| `fontSize`      | `string`           | The size of the font.                                        |
-| `clamp`         | `[number, number]` | A tuple defining the minimum and maximum sizes for clamping. |
+| Property         | Type               | Description                                                  |
+| ---------------- | ------------------ | ------------------------------------------------------------ |
+| `fontFamily`     | `string`           | The font family to be applied.                               |
+| `fontWeight`     | `string \| number` | The weight of the font.                                      |
+| `lineHeight`     | `string \| number` | The height of the line.                                      |
+| `letterSpacing`  | `string`           | The spacing between letters.                                 |
+| `textTransform`  | `string`           | The transformation applied to the text (e.g., uppercase).    |
+| `fontSize`       | `string`           | The size of the font.                                        |
+| `clamp`          | `[number, number]` | A tuple defining the minimum and maximum sizes for clamping. |
+| `color`          | `string`           | The color of the text.                                       |
+| `fontStyle`      | `string`           | The style of the font (e.g., normal, italic, oblique).       |
+| `textDecoration` | `string`           | Decorations added to the text (e.g., underline).             |
+| `textShadow`     | `string`           | Adds shadow to the text.                                     |
+| `whiteSpace`     | `string`           | Specifies how white space inside an element is handled.      |
+| `wordSpacing`    | `string`           | The spacing between words.                                   |
+| `textOverflow`   | `string`           | How overflowed content is signaled to the user.              |
+| `direction`      | `string`           | Sets the text direction (e.g., ltr, rtl).                    |
+| `writingMode`    | `string`           | Defines the layout of text (horizontal or vertical).         |
+| `textRendering`  | `string`           | Provides rendering hints to the browser.                     |
+| `hyphens`        | `string`           | Specifies how words should be hyphenated.                    |
+
 
 ### Clamp Property
 
@@ -197,6 +213,49 @@ const customTexts = {
 
 When using custom styled keys as tailwind classes, they'll be named as `headline-your-key-name`. For example, if your key was `'custom-display'` in the `customHeadlines` object, it would be used as `'headline-custom-display'` class in tailwind.
 
+## Custom Aliases for Styles
+
+If you're replaceing an existing style in the defaults, you can add a custom alias for the style. This is done by adding a `classAlias` key to the style object.
+
+```tsx
+// type-config.ts
+
+const customHeadlines = {
+  'display-xl': {
+    fontFamily: 'Arial, sans-serif',
+    classAlias: 'primary-headline',
+  },
+  // other headline styles
+}
+```
+
+## Disable default type styles
+
+To disable the default type styles, set the `disableDefaults` option to `true`.
+
+```tsx
+// tailwind.config.ts
+
+import { buenTypeTailwind } from "@buen/type";
+import { customHeadlines, customTexts } from "./type-config";
+
+function typePlugin({ addUtilities }) {
+  buenTypeTailwind(
+    { addUtilities },
+    {
+      disableDefaults: true,
+    },
+  );
+};
+
+module.exports = {
+  //  ...
+  plugins: [
+    typePlugin
+  ]
+};
+```
+
 ## Contributing
 
 This project is maintained by John Choura, but it open to contributions from anyone. See [CONTRIBUTORS](https://github.com/johnchourajr/buen-type/blob/main/CONTRIBUTORS.md) for a guide on how to contribute.

diff --git a/example/src/components/TypeScale.tsx b/example/src/components/TypeScale.tsx
@@ -39,10 +39,10 @@ export function TypeScale({ typeData }: TypeScaleProps) {
   return (
     <>
       {Object.keys(typeData).map((key) => {
-        const { _className } = typeData[key];
+        const { _id } = typeData[key];
 
         function style() {
-          switch (_className) {
+          switch (_id) {
             case "headline-display-xxl":
               return "headline-display-xxl";
             case "headline-display-xl":
@@ -73,7 +73,7 @@ export function TypeScale({ typeData }: TypeScaleProps) {
         return (
           <div key={key} className="mb-10">
             <h2 className={clsx("text-start font-bold", style())}>
-              {sanitizeTitle(_className?.toString() || key)}
+              {sanitizeTitle(_id?.toString() || key)}
             </h2>
             <pre>
               <code className="text-body font-mono">

diff --git a/example/tailwind.config.ts b/example/tailwind.config.ts
@@ -1,6 +1,13 @@
 import type { Config } from "tailwindcss";
+import { PluginAPI } from "tailwindcss/types/config";
 import { buenTypeTailwind } from "../src/index";
 
+function typePlugin({ addUtilities }: PluginAPI) {
+  buenTypeTailwind({ addUtilities }, {
+    disableDefaults: false,
+  });
+};
+
 const config: Config = {
   content: [
     "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
@@ -20,6 +27,6 @@ const config: Config = {
       },
     },
   },
-  plugins: [buenTypeTailwind],
+  plugins: [typePlugin],
 };
 export default config;
diff --git a/jsr.json b/jsr.json
@@ -1,6 +1,6 @@
 {
   "name": "@buen/type",
-  "version": "1.0.12",
+  "version": "1.1.0",
   "exports": "./src/index.ts",
   "publish": {
     "include": ["src/**/*.ts", "src/defaults.ts", "src/types.ts", "README.md"],

diff --git a/src/defaults.ts b/src/defaults.ts
@@ -5,46 +5,45 @@ import { TypeDefinitionHeadlines, TypeDefinitionTexts } from "./types.ts";
  */
 export const DEFAULT_HEADLINE: TypeDefinitionHeadlines = {
   "display-xxl": {
-    _className: "headline-display-xxl",
+    _id: "headline-display-xxl",
+    classAlias: ["main-headline"],
     fontWeight: "bold",
     clamp: [6, 12],
     letterSpacing: "-0.05em",
-    lineHeight: 1,
   },
   "display-xl": {
-    _className: "headline-display-xl",
+    _id: "headline-display-xl",
     fontWeight: "bold",
     clamp: [4.5, 9],
     letterSpacing: "-0.05em",
-    lineHeight: 1,
   },
   "display-lg": {
-    _className: "headline-display-lg",
+    _id: "headline-display-lg",
     fontWeight: "bold",
     clamp: [3.5, 5],
     letterSpacing: "-0.05em",
     lineHeight: 1,
   },
   "display-md": {
-    _className: "headline-display-md",
+    _id: "headline-display-md",
     fontWeight: "bold",
     clamp: [3, 4],
     letterSpacing: "-0.05em",
     lineHeight: 1,
   },
   "display-sm": {
-    _className: "headline-display-sm",
+    _id: "headline-display-sm",
     fontWeight: "bold",
     clamp: [1.5, 2],
     letterSpacing: "-0.05em",
     lineHeight: 1,
   },
   "display-xs": {
-    _className: "headline-display-xs",
+    _id: "headline-display-xs",
     fontWeight: "bold",
     clamp: [1, 1],
     letterSpacing: "-0em",
-    lineHeight: 1,
+    lineHeight: 1
   },
 };
 
@@ -53,35 +52,35 @@ export const DEFAULT_HEADLINE: TypeDefinitionHeadlines = {
  */
 export const DEFAULT_TEXT: TypeDefinitionTexts = {
   title: {
-    _className: "text-title",
+    _id: "text-title",
     fontSize: "1.5rem",
     lineHeight: 1.25,
     fontWeight: "normal",
     letterSpacing: "0em",
   },
   paragraph: {
-    _className: "text-paragraph",
+    _id: "text-paragraph",
     fontSize: "1.25rem",
     lineHeight: 1.35,
     fontWeight: "normal",
     letterSpacing: "0em",
   },
   string: {
-    _className: "text-string",
+    _id: "text-string",
     fontSize: ".9rem",
     lineHeight: 1.25,
     fontWeight: "normal",
     letterSpacing: "0em",
   },
   body: {
-    _className: "text-body",
+    _id: "text-body",
     fontSize: "0.8rem",
     lineHeight: 1.25,
     fontWeight: "normal",
     letterSpacing: "0em",
   },
   caption: {
-    _className: "text-caption",
+    _id: "text-caption",
     fontSize: "0.65rem",
     lineHeight: 1.25,
     fontWeight: "normal",

diff --git a/src/tailwind-plugin/buenTypeTailwind.ts b/src/tailwind-plugin/buenTypeTailwind.ts
@@ -16,7 +16,7 @@ type AddUtilities = {
  */
 export function buenTypeTailwind(
   { addUtilities }: { addUtilities: AddUtilities },
-  customDefinitions?: CustomTypeDefinitions,
+  options?: CustomTypeDefinitions,
 ): void {
   const generateStyles = (definition: TypeDefinition) => {
     let styles: TypeDefinition = {
@@ -26,6 +26,16 @@ export function buenTypeTailwind(
       letterSpacing: definition.letterSpacing,
       textTransform: definition.textTransform,
       fontSize: definition.fontSize,
+      fontStyle: definition.fontStyle,
+      textDecoration: definition.textDecoration,
+      textShadow: definition.textShadow,
+      whiteSpace: definition.whiteSpace,
+      wordSpacing: definition.wordSpacing,
+      textOverflow: definition.textOverflow,
+      direction: definition.direction,
+      writingMode: definition.writingMode,
+      textRendering: definition.textRendering,
+      hyphens: definition.hyphens,
     };
     if (definition.fontSize) {
       styles.fontSize = definition.fontSize;
@@ -41,17 +51,25 @@ export function buenTypeTailwind(
    * @todo Look into using deepmerge to merge the default and custom definitions
    */
 
+  const defaultHeadlines = options?.disableDefaults ? null : DEFAULT_HEADLINE;
   const mergedHeadlines = {
-    ...DEFAULT_HEADLINE,
-    ...customDefinitions?.customHeadlines,
+    ...defaultHeadlines,
+    ...options?.customHeadlines,
   };
-  const mergedTexts = { ...DEFAULT_TEXT, ...customDefinitions?.customTexts };
+
+  const defaultTexts = options?.disableDefaults ? null : DEFAULT_TEXT;
+  const mergedTexts = { ...defaultTexts, ...options?.customTexts };
 
   let headlineUtilities: Record<string, any> = {};
   typedKeys(mergedHeadlines).forEach((key) => {
     const style = mergedHeadlines[key];
     if (style) {
       headlineUtilities[`.headline-${key}`] = generateStyles(style);
+      if (style.classAlias) {
+        style.classAlias.forEach(alias => {
+          headlineUtilities[`.${alias}`] = generateStyles(style);
+        });
+      }
     }
   });
 
@@ -60,6 +78,11 @@ export function buenTypeTailwind(
     const style = mergedTexts[key];
     if (style) {
       textUtilities[`.text-${key}`] = generateStyles(style);
+      if (style.classAlias) {
+        style.classAlias.forEach(alias => {
+          textUtilities[`.text-${alias}`] = generateStyles(style);
+        });
+      }
     }
   });
 

diff --git a/src/types.ts b/src/types.ts
@@ -23,33 +23,57 @@ export type DefaultTextTypes =
 /**
  * Type definition properties
  *
- * @todo explore adding more properties,
  * @todo refactor to import types from @react/types
+ *
+ * @param classAlias - e.g., ["main-headline"]
+ * @param fontFamily - e.g., Arial, sans-serif, monospace
+ * @param fontWeight - e.g., normal, bold, 400, 700
+ * @param lineHeight - e.g., 1.5, 150%, 1.5em
+ * @param letterSpacing - e.g., 0.1em, 1px
+ * @param textTransform - e.g., uppercase, lowercase, capitalize, none
+ * @param fontSize - e.g., 1.5rem, 1.5em, 150%, 1.5vw
+ * @param clamp - e.g., [1, 2]
+ * @param color - e.g., #000, rgba(0, 0, 0, 0.5)
+ * @param fontStyle - e.g., normal, italic, oblique
+ * @param textDecoration - e.g., underline, overline, line-through, none
+ * @param textAlign - e.g., left, right, center, justify
+ * @param textShadow - e.g., 1px 1px 2px black
+ * @param whiteSpace - e.g., normal, nowrap, pre
+ * @param wordSpacing - e.g., normal, 0.25em
+ * @param textOverflow - e.g., clip, ellipsis
+ * @param textIndent - e.g., 50px, 5%
+ * @param direction - e.g., ltr, rtl
+ * @param writingMode - e.g., horizontal-tb, vertical-rl
+ * @param textRendering - e.g., auto, optimizeLegibility, geometricPrecision
+ * @param hyphens - e.g., none, manual, auto
  */
 export type TypeDefinition = {
-  _className?: string;
-  fontFamily?: string;
-  fontWeight?: string | number;
-  lineHeight?: string | number;
-  letterSpacing?: string;
-  textTransform?: string;
-  fontSize?: string;
+    _id?: string;
+  classAlias?: string[] | ["some-class-alias"];
+  fontFamily?: string | "sans-serif" | 'monospace';
+  fontWeight?: string | number | 'normal' | 'bold' | 400 | 700;
+  lineHeight?: string | number | 1.5 | '150%' | '1.5em';
+  letterSpacing?: string | '-0.01em';
+  textTransform?: string | 'uppercase' | 'lowercase' | 'capitalize' | 'none';
+  fontSize?: string | '1.5rem' | '1.5em' | '150%' | '1.5vw';
   clamp?: [number, number];
+  fontStyle?: string | 'normal' | 'italic' | 'oblique';
+  textDecoration?: string | 'underline' | 'overline' | 'line-through' | 'none';
+  textShadow?: string | '1px 1px 2px black';
+  whiteSpace?: string | 'normal' | 'nowrap' | 'pre';
+  wordSpacing?: string | 'normal' | '0.25em';
+  textOverflow?: string | 'clip' | 'ellipsis';
+  direction?: string | 'ltr' | 'rtl';
+  writingMode?: string | 'horizontal-tb' | 'vertical-rl';
+  textRendering?: string | 'auto' | 'optimizeLegibility' | 'geometricPrecision';
+  hyphens?: string | 'none' | 'manual' | 'auto';
 };
 
+
 /**
- * CSS output properties, mirrors TypeDefinition excluding clamp and _className
- *
- * @todo refactor to reference TypeDefinition and exclude _className and clamp
+ * CSS output properties, mirrors TypeDefinition excluding clamp and _id
  */
-export type CSSOutput = {
-  fontFamily?: string;
-  fontWeight?: string | number;
-  lineHeight?: string | number;
-  letterSpacing?: string;
-  textTransform?: string;
-  fontSize?: string;
-};
+export type CSSOutput = Omit<TypeDefinition, 'classAlias' | 'clamp'>;
 
 /**
  * Type definitions object
@@ -75,4 +99,5 @@ export type TypeDefinitionTexts = Record<DefaultTextTypes, TypeDefinition>;
 export type CustomTypeDefinitions = {
   customHeadlines?: Record<string, TypeDefinition>;
   customTexts?: Record<string, TypeDefinition>;
+  disableDefaults?: boolean;
 };