@kalink-ui/seedly 0.1.0

package/src/styles/styles.mdx

@@ -0,0 +1,98 @@
+import { Meta } from '@storybook/addon-docs';
+
+<Meta title="Styles/Styles Documentation" />
+
+# Styles Documentation
+
+This document provides an overview of two important files in our styling system: `contract.css.ts` and `seed.tsx`.
+
+## contract.css.ts
+
+The `contract.css.ts` file defines the type contract for our design system's typography. It establishes a consistent structure for different text styles across various sizes.
+
+### Structure
+
+The type contract is organized into the following categories:
+
+- `display`
+- `headline`
+- `title`
+- `label`
+- `body`
+
+Each category has three size variants:
+
+- `large`
+- `medium`
+- `small`
+
+### Usage
+
+This contract ensures that all typography in the application follows a consistent structure. It can be used to create theme variations and maintain a coherent typographic scale across the entire design system.
+
+Example of the structure:
+
+```typescript
+type: {
+  display: {
+    large: typeContract,
+    medium: typeContract,
+    small: typeContract,
+  },
+  // ... other categories
+}
+```
+
+## seed.tsx
+
+The `seed.tsx` file provides a foundation for creating flexible, polymorphic components with built-in support for design system styles.
+
+### Key Features
+
+1. **Polymorphic Components**: Allows components to change their root HTML element.
+2. **Sprinkles Integration**: Incorporates the Sprinkles CSS-in-JS solution for applying atomic styles.
+3. **Type Safety**: Ensures type safety for props and element types.
+
+### Main Functions
+
+#### `plantSeed`
+
+This function creates a base component (Seed) that can be used to build other components in the design system.
+
+Parameters:
+
+- `sprinkles`: A Sprinkles function for applying atomic styles.
+- `defaultClassName`: An optional default class name for the component.
+
+Usage:
+
+```jsx
+import { plantSeed } from './seed';
+import { sprinkles } from './your-sprinkles-file';
+
+const Sprout = plantSeed({ sprinkles });
+
+// Use Sprout as a base for other components
+const Box = (props) => <Sprout {...props} />;
+```
+
+### Types
+
+#### `SeedProps`
+
+This type combines polymorphic component props with Sprinkles props:
+
+```typescript
+type SeedProps<
+  TUse extends ElementType,
+  TSprinklesFn extends SprinklesFnBase,
+> = PolymorphicComponentProps<TUse> & GetSprinkles<TSprinklesFn>;
+```
+
+### Benefits
+
+- **Consistency**: Ensures all components built with `plantSeed` have consistent prop interfaces.
+- **Flexibility**: Allows easy creation of new components with full access to design system styles.
+- **Performance**: Leverages Sprinkles for efficient CSS generation and application.
+
+By using `contract.css.ts` and `seed.tsx` together, you can create a robust, type-safe, and flexible foundation for your design system components.

package/src/styles/system-contract.css.ts

@@ -0,0 +1,144 @@
+import { createThemeContract } from '@vanilla-extract/css';
+
+const typeContract = {
+  font: null,
+  weight: null,
+  lineHeight: null,
+  tracking: null,
+  size: null,
+};
+
+export const sys = createThemeContract({
+  layout: {
+    direction: null,
+    measure: null,
+  },
+
+  color: {
+    background: null,
+    foreground: null,
+    muted: null,
+    outline: null,
+  },
+
+  state: {
+    hovered: {
+      opacity: null,
+    },
+    focused: {
+      opacity: null,
+    },
+    pressed: {
+      opacity: null,
+    },
+  },
+
+  shape: {
+    corner: {
+      none: null,
+      sharp: null,
+      small: null,
+      medium: null,
+      rounded: null,
+      circle: null,
+    },
+  },
+
+  elevation: {
+    none: null,
+    minimal: null,
+    low: null,
+    moderate: null,
+    high: null,
+    peak: null,
+  },
+
+  motion: {
+    duration: {
+      short: {
+        1: null,
+        2: null,
+        3: null,
+        4: null,
+      },
+      medium: {
+        1: null,
+        2: null,
+        3: null,
+        4: null,
+      },
+      long: {
+        1: null,
+        2: null,
+        3: null,
+        4: null,
+      },
+    },
+
+    easing: {
+      standard: null,
+      decelerate: {
+        standard: null,
+        emphasized: null,
+      },
+      accelerate: {
+        standard: null,
+        emphasized: null,
+      },
+    },
+  },
+
+  typography: {
+    display: {
+      large: typeContract,
+      medium: typeContract,
+      small: typeContract,
+    },
+
+    headline: {
+      large: typeContract,
+      medium: typeContract,
+      small: typeContract,
+    },
+
+    title: {
+      large: typeContract,
+      medium: typeContract,
+      small: typeContract,
+    },
+
+    label: {
+      large: typeContract,
+      medium: typeContract,
+      small: typeContract,
+    },
+
+    body: {
+      large: typeContract,
+      medium: typeContract,
+      small: typeContract,
+    },
+  },
+
+  spacing: {
+    0: null,
+    1: null,
+    2: null,
+    3: null,
+    4: null,
+    5: null,
+    6: null,
+    7: null,
+    8: null,
+    9: null,
+    10: null,
+    11: null,
+    12: null,
+    13: null,
+    14: null,
+    15: null,
+    16: null,
+    17: null,
+    18: null,
+  },
+});

package/src/types/index.ts

@@ -0,0 +1,5 @@
+export {
+  type PolymorphicComponentProps,
+  type DistributiveOmit,
+  type UnwrapArray,
+} from './utils.types';

package/src/types/utils.types.ts

@@ -0,0 +1,15 @@
+import type { ComponentPropsWithRef, ElementType } from 'react';
+
+/* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+export type DistributiveOmit<T, TOmitted extends PropertyKey> = T extends any
+  ? Omit<T, TOmitted>
+  : never;
+
+export type UnwrapArray<R> = R extends unknown[] ? UnwrapArray<R[number]> : R;
+
+export type PolymorphicComponentProps<TUse extends ElementType> = {
+  use?: TUse;
+} & DistributiveOmit<
+  ComponentPropsWithRef<ElementType extends TUse ? 'div' : TUse>,
+  'use'
+>;

package/src/utils/__tests__/extract-sprinkles-props.test.ts

@@ -0,0 +1,101 @@
+import { describe, test } from '@std/testing/bdd';
+import { spy } from '@std/testing/mock';
+import { expect } from '@std/expect';
+
+import {
+  extractSprinklesProps,
+  type SprinklesFnBase,
+} from '@/utils/extract-sprinkles-props';
+
+describe('extractSprinklesProps', () => {
+  const mockSprinkles: SprinklesFnBase = {
+    properties: new Set(['color', 'fontSize', 'padding']),
+  } as SprinklesFnBase;
+
+  test('should correctly separate sprinkles props from component props', () => {
+    const props = {
+      color: 'red',
+      fontSize: '16px',
+      padding: '10px',
+      onClick: spy(),
+      className: 'custom-class',
+    };
+
+    const [sprinkleProps, componentProps] = extractSprinklesProps(
+      props,
+      mockSprinkles,
+    );
+
+    expect(sprinkleProps).toEqual({
+      color: 'red',
+      fontSize: '16px',
+      padding: '10px',
+    });
+
+    expect(componentProps).toEqual({
+      onClick: expect.any(Function),
+      className: 'custom-class',
+    });
+  });
+
+  test('should handle props with no sprinkles properties', () => {
+    const props = {
+      onClick: spy(),
+      className: 'custom-class',
+    };
+
+    const [sprinkleProps, componentProps] = extractSprinklesProps(
+      props,
+      mockSprinkles,
+    );
+
+    expect(sprinkleProps).toEqual({});
+    expect(componentProps).toEqual(props);
+  });
+
+  test('should handle props with only sprinkles properties', () => {
+    const props = {
+      color: 'blue',
+      fontSize: '14px',
+    };
+
+    const [sprinkleProps, componentProps] = extractSprinklesProps(
+      props,
+      mockSprinkles,
+    );
+
+    expect(sprinkleProps).toEqual(props);
+    expect(componentProps).toEqual({});
+  });
+
+  test('should handle empty props object', () => {
+    const props = {};
+
+    const [sprinkleProps, componentProps] = extractSprinklesProps(
+      props,
+      mockSprinkles,
+    );
+
+    expect(sprinkleProps).toEqual({});
+    expect(componentProps).toEqual({});
+  });
+
+  test('should handle sprinkles function with empty properties set', () => {
+    const emptySprinkles: SprinklesFnBase = {
+      properties: new Set(),
+    } as SprinklesFnBase;
+
+    const props = {
+      color: 'green',
+      onClick: spy(),
+    };
+
+    const [sprinkleProps, componentProps] = extractSprinklesProps(
+      props,
+      emptySprinkles,
+    );
+
+    expect(sprinkleProps).toEqual({});
+    expect(componentProps).toEqual(props);
+  });
+});

package/src/utils/__tests__/is-object.test.ts

@@ -0,0 +1,24 @@
+import { isObject } from "@/utils/is-object.ts";
+import { describe, it } from "@std/testing/bdd";
+import { expect } from "@std/expect";
+
+describe("isObject", () => {
+  it("should return true if value is an object", () => {
+    expect(isObject({})).toEqual(true);
+  });
+
+  it("should return false if value is an array", () => {
+    expect(isObject([])).toEqual(false);
+  });
+
+  it("should return false if value is null or undefined", () => {
+    expect(isObject(null)).toEqual(false);
+    expect(isObject(undefined)).toEqual(false);
+  });
+
+  it("should return false if value is any scalar", () => {
+    expect(isObject(1)).toEqual(false);
+    expect(isObject("foo")).toEqual(false);
+    expect(isObject(true)).toEqual(false);
+  });
+});

package/src/utils/__tests__/map-contract-vars.test.ts

@@ -0,0 +1,34 @@
+import { mapContractVars } from "@/utils/map-contract-vars.ts";
+import { describe, test } from "@std/testing/bdd";
+import { expect } from "@std/expect";
+
+describe("mapContractVars", () => {
+  test("should map contract vars", () => {
+    const contract = {
+      foo: "foo",
+      bar: "bar",
+    };
+
+    const result = mapContractVars(contract, (key) => ({
+      padding: `var(--${key})`,
+      vars: {
+        [`--${key}`]: contract[key],
+      },
+    }));
+
+    expect(result).toEqual({
+      foo: {
+        padding: "var(--foo)",
+        vars: {
+          "--foo": "foo",
+        },
+      },
+      bar: {
+        padding: "var(--bar)",
+        vars: {
+          "--bar": "bar",
+        },
+      },
+    });
+  });
+});

package/src/utils/arg-types/arg-types-from-recipe.ts

@@ -0,0 +1,37 @@
+import { type ComplexStyleRule } from '@vanilla-extract/css';
+import { type RuntimeFn } from '@vanilla-extract/recipes';
+
+type RecipeStyleRule = ComplexStyleRule | string;
+type VariantDefinitions = Record<string, RecipeStyleRule>;
+type VariantGroups = Record<string, VariantDefinitions>;
+
+export function argTypesFromRecipe(
+  recipe: RuntimeFn<VariantGroups>,
+  excludes: string[] = [],
+) {
+  return Object.entries(recipe.classNames.variants).reduce(
+    (acc, [name, variant]) => {
+      if (excludes.includes(name)) {
+        return acc;
+      }
+
+      const options = Object.keys(variant);
+      let control = options.length > 5 ? 'select' : 'radio';
+
+      if (options.length === 1 && options[0] === 'true') {
+        options.push('false');
+        control = 'boolean';
+      }
+
+      return {
+        ...acc,
+        [name]: {
+          control,
+          options,
+          table: { category: 'Styling props' },
+        },
+      };
+    },
+    {},
+  );
+}

package/src/utils/arg-types/arg-types-from-sprinkles.ts

@@ -0,0 +1,43 @@
+import { isObject } from '@kalink/ui/utils';
+
+type ArgTypesFromSprinklesProps = {
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  props: Record<string, any>;
+  excludes?: string[];
+  category?: string;
+} & {};
+
+export function argTypesFromSprinkles({
+  props,
+  excludes = [],
+  category = 'Sprinkles props',
+}: ArgTypesFromSprinklesProps) {
+  return Object.entries(props).reduce((acc, [name]) => {
+    if (Array.isArray(excludes) && excludes.includes(name)) {
+      return acc;
+    }
+
+    let options = props[name] || [];
+    let control = 'select';
+
+    if (options.length === 1 && options[0] === 'true') {
+      options.push('false');
+      control = 'boolean';
+    }
+
+    if (isObject(options)) {
+      options = Object.fromEntries(
+        Object.keys(options).map((key) => [key, key]),
+      );
+    }
+
+    return {
+      ...acc,
+      [name]: {
+        control,
+        options,
+        table: { category },
+      },
+    };
+  }, {});
+}

package/src/utils/arg-types/common/composable.ts

@@ -0,0 +1,13 @@
+export const composable = {
+  children: {
+    control: false,
+    description: 'Content of the component.',
+    defaultValue: '',
+    table: {
+      category: 'Intrinsic props',
+      type: {
+        summary: 'ReactNode',
+      },
+    },
+  },
+};

package/src/utils/arg-types/common/index.ts

@@ -0,0 +1,4 @@
+export { composable } from './composable';
+export { polymorphic } from './polymorphic';
+export { referable } from './referable';
+export { stylable } from './stylable';

package/src/utils/arg-types/common/polymorphic.ts

@@ -0,0 +1,14 @@
+export const polymorphic = {
+  use: {
+    control: false,
+    description:
+      'The component used to render the root node of the component. Either a string to use an `JSX.IntrinsicElements` or a component reference to use a `React.ComponentType`',
+    defaultValue: '',
+    table: {
+      category: 'Intrinsic props',
+      type: {
+        summary: 'ElementType',
+      },
+    },
+  },
+};

package/src/utils/arg-types/common/referable.ts

@@ -0,0 +1,10 @@
+export const referable = {
+  ref: {
+    control: false,
+    description: 'Ref passed to the component root.',
+    defaultValue: '',
+    table: {
+      category: 'Intrinsic props',
+    },
+  },
+};

package/src/utils/arg-types/common/stylable.ts

@@ -0,0 +1,14 @@
+export const stylable = {
+  className: {
+    control: false,
+    description:
+      'A class name string passed to the component. Merged with the inner class names.',
+    defaultValue: '',
+    table: {
+      category: 'Intrinsic props',
+      type: {
+        summary: 'string',
+      },
+    },
+  },
+};

package/src/utils/arg-types/common-args.ts

@@ -0,0 +1,26 @@
+/* eslint-disable import/namespace */
+import * as CommonArgDefs from './common';
+
+export enum CommonArgs {
+  COMPOSABLE = 'composable',
+  POLYMORPHIC = 'polymorphic',
+  STYLABLE = 'stylable',
+  REFERABLE = 'referable',
+}
+
+export function commonArgs(args: CommonArgs[]) {
+  const argTypes: Partial<Record<string, object>> = {};
+  const knownArgs = Object.values(CommonArgs);
+
+  for (const arg of args) {
+    if (!knownArgs.includes(arg)) {
+      continue;
+    }
+
+    for (const argDef in CommonArgDefs[arg]) {
+      argTypes[argDef] = (CommonArgDefs[arg] as Record<string, object>)[argDef];
+    }
+  }
+
+  return argTypes;
+}

package/src/utils/arg-types/index.ts

@@ -0,0 +1,3 @@
+export { argTypesFromRecipe } from './arg-types-from-recipe';
+export { argTypesFromSprinkles } from './arg-types-from-sprinkles';
+export { commonArgs, CommonArgs } from './common-args';

package/src/utils/extract-sprinkles-props.ts

@@ -0,0 +1,46 @@
+import type { SprinklesProperties } from '@vanilla-extract/sprinkles';
+import type { UnknownRecord } from 'type-fest';
+
+export interface SprinklesFnBase {
+  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
+  (...args: any): string;
+  properties: Set<string>;
+}
+
+export type GetSprinkles<T extends SprinklesFnBase> = Parameters<T>[0];
+
+export type SprinklesProps<TSprinklesFnBase extends SprinklesFnBase> =
+  TSprinklesFnBase['properties'] extends Set<infer T>
+    ? {
+        [KeyType in keyof T]: T[KeyType] extends SprinklesProperties
+          ? KeyType
+          : never;
+      }
+    : never;
+
+/**
+ * Extracts the sprinkles properties from the given component props,
+ * returning an array containing the extracted sprinkle props and
+ * the remaining component props.
+ */
+export const extractSprinklesProps = <
+  ComponentProps extends UnknownRecord,
+  SprinklesFn extends SprinklesFnBase,
+>(
+  props: ComponentProps,
+  sprinkles: SprinklesFn,
+) => {
+  const sprinkleProps: Record<string, unknown> = {};
+  const componentProps: Record<string, unknown> = {};
+
+  for (const prop of Object.keys(props)) {
+    if (sprinkles.properties.has(prop)) {
+      sprinkleProps[prop] = props[prop];
+      continue;
+    }
+
+    componentProps[prop] = props[prop];
+  }
+
+  return [sprinkleProps, componentProps];
+};

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export { extractSprinklesProps } from './extract-sprinkles-props';
+export { isObject } from './is-object';
+export { mapContractVars } from './map-contract-vars';

package/src/utils/is-object.ts

@@ -0,0 +1,3 @@
+export const isObject = <T extends object>(value: unknown): value is T => {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+};

package/src/utils/map-contract-vars.ts

@@ -0,0 +1,10 @@
+type MappedVars = Record<string, unknown>;
+
+export const mapContractVars = <TContract extends Record<string, unknown>>(
+  contractVars: TContract,
+  mapFn: (key: keyof TContract) => MappedVars,
+) => {
+  return Object.fromEntries(
+    Object.keys(contractVars).map((key) => [key, mapFn(key)]),
+  ) as Record<keyof TContract, MappedVars>;
+};