creactive 0.0.55 → 0.0.56

package/source/contexts/theme/theme.types.ts

@@ -0,0 +1,284 @@
+import type { FunctionComponent, PropsWithChildren } from 'react'
+
+/**
+ * Theme RGB color type.
+ * Should be used to specify theme colors.
+ * Number instead of 0-255 union to avoid too complex union type.
+ */
+export type ThemeColorRGB = `rgb(${number},${number},${number})`
+
+/**
+ * Theme font weight type.
+ * Should be used to specify theme font weight.
+ */
+export type ThemeFontWeight =
+  | 100
+  | 200
+  | 300
+  | 400
+  | 500
+  | 600
+  | 700
+  | 800
+  | 900
+
+/**
+ * Theme context value interface.
+ * Contains all theme tokens you may need.
+ * This tokens are used inside components for styling.
+ * This tokens can be also accesed via theme context outside.
+ */
+export interface ThemeContextValue {
+  /**
+   * Base foreground 100 color token.
+   * The least contrasting color in the foreground palette.
+   * Intended for nearly invisible elements.
+   */
+  colorForegroundBase100: ThemeColorRGB
+  /**
+   * Base foreground 200 color token.
+   * Still meant to be barely visible.
+   * Can help create a subtle sense of hierarchy.
+   */
+  colorForegroundBase200: ThemeColorRGB
+  /**
+   * Base foreground 300 color token.
+   * Suitable for slightly readable text or elements.
+   */
+  colorForegroundBase300: ThemeColorRGB
+  /**
+   * Base foreground 400 color token.
+   * A secondary color for secondary elements.
+   * If a secondary element has multiple levels, this is for the lower one.
+   */
+  colorForegroundBase400: ThemeColorRGB
+  /**
+   * Base foreground 500 color token.
+   * Also useful for secondary elements on low-contrast backgrounds.
+   */
+  colorForegroundBase500: ThemeColorRGB
+  /**
+   * Base foreground 600 color token.
+   * Ideal for secondary elements and less prominent text.
+   */
+  colorForegroundBase600: ThemeColorRGB
+  /**
+   * Base foreground 700 color token.
+   * Used for default elements on higher contrast backgrounds.
+   * Also suitable for slightly subdued elements.
+   */
+  colorForegroundBase700: ThemeColorRGB
+  /**
+   * Base foreground 800 color token.
+   * The default value for the text component.
+   * Ideal for high-contrast text and key elements.
+   */
+  colorForegroundBase800: ThemeColorRGB
+  /**
+   * Base foreground 900 color token.
+   * Similar to 800 but better suited for lower-contrast backgrounds.
+   */
+  colorForegroundBase900: ThemeColorRGB
+  /**
+   * Inverse foreground 100 color token.
+   * The least contrasting color in the inverse foreground palette.
+   * Intended for nearly invisible elements on inverse backgrounds.
+   */
+  colorForegroundInverse100: ThemeColorRGB
+  /**
+   * Inverse foreground 200 color token.
+   * Can help create a subtle sense of hierarchy on inverse backgrounds.
+   * Also almost invisible, but a bit more contrasting than 100.
+   */
+  colorForegroundInverse200: ThemeColorRGB
+  /**
+   * Inverse foreground 300 color token.
+   * Suitable for slightly readable text or elements on inverse backgrounds.
+   */
+  colorForegroundInverse300: ThemeColorRGB
+  /**
+   * Inverse foreground 400 color token.
+   * A secondary color for secondary elements on inverse backgrounds.
+   * If a secondary element has multiple levels, this is for the lower one.
+   */
+  colorForegroundInverse400: ThemeColorRGB
+  /**
+   * Inverse foreground 500 color token.
+   * Also useful for secondary elements on low-contrast inverse backgrounds.
+   */
+  colorForegroundInverse500: ThemeColorRGB
+  /**
+   * Inverse foreground 600 color token.
+   * Ideal for secondary elements on inverse backgrounds.
+   */
+  colorForegroundInverse600: ThemeColorRGB
+  /**
+   * Inverse foreground 700 color token.
+   * Used for default elements on higher contrast inverse backgrounds.
+   * Also suitable for slightly subdued elements.
+   */
+  colorForegroundInverse700: ThemeColorRGB
+  /**
+   * Inverse foreground 800 color token.
+   * Ideal for high-contrast text on inverse background.
+   */
+  colorForegroundInverse800: ThemeColorRGB
+  /**
+   * Inverse foreground 900 color token.
+   * Similar to 800 but can be a bit more contrasting.
+   * Suitable when you need even more contrast on inverse background.
+   */
+  colorForegroundInverse900: ThemeColorRGB
+  /**
+   * Base font family token.
+   * Supposed to be used by most components.
+   * If you don't known what font family to use - use this one.
+   */
+  fontFamilyBase: string
+  /**
+   * Base thin font weight token.
+   * Ideal for very delicate and decorative, large, elegant hero text.
+   */
+  fontWeightBaseThin: ThemeFontWeight
+  /**
+   * Base extra-light font weight token.
+   * Use for large, airy headings or subtle interface elements.
+   * Slightly more readable than extra-thin, but still decorative.
+   */
+  fontWeightBaseExtraLight: ThemeFontWeight
+  /**
+   * Base light font weight token.
+   * Suitable for subheadings, muted captions, and soft labels.
+   */
+  fontWeightBaseLight: ThemeFontWeight
+  /**
+   * Base regular font weight token.
+   * For the most common text elements in your interface.
+   * When unsure about font weight, this is the default option.
+   */
+  fontWeightBaseRegular: ThemeFontWeight
+  /**
+   * Base medium font weight token.
+   * Suitable for labels, buttons, and small subheadings.
+   * Slightly emphasized, providing better readability.
+   */
+  fontWeightBaseMedium: ThemeFontWeight
+  /**
+   * Base semi-bold font weight token.
+   * Provides stronger emphasis without being overwhelming.
+   * Ideal for section headers, emphasized text, and card titles.
+   */
+  fontWeightBaseSemibold: ThemeFontWeight
+  /**
+   * Base bold font weight token.
+   * For high emphasis on important elements.
+   * Use for main headings and strong call-to-action buttons.
+   */
+  fontWeightBaseBold: ThemeFontWeight
+  /**
+   * Extra-bold font weight token.
+   * Perfect for promo banners and large impactful headings.
+   */
+  fontWeightBaseExtraBold: ThemeFontWeight
+  /**
+   * Base black font weight token.
+   * Extreme emphasis for rare, dramatic cases.
+   * Great for headlines in posters and highly attention-grabbing elements.
+   */
+  fontWeightBaseBlack: ThemeFontWeight
+  /**
+   * Base 2 times extra-small font size token.
+   * Use this size for tiny text elements like captions.
+   * It represents the smallest readable text in your interface.
+   */
+  fontSizeBaseX2S: number
+  /**
+   * Base extra-small font size token.
+   * Suitable for subtitles or the smallest readable text, for example.
+   */
+  fontSizeBaseXS: number
+  /**
+   * Base small font size token.
+   * Can be used for smaller labels or captions among medium text.
+   * Also suitable for titles in smaller 2x small text.
+   */
+  fontSizeBaseSM: number
+  /**
+   * Base medium font size token.
+   * Intended for most text elements.
+   * If unsure about which font size to use, this is the default option.
+   */
+  fontSizeBaseMD: number
+  /**
+   * Base large font size token.
+   * Suitable for fourth-level page titles.
+   * Can also be used for larger labels or captions among medium text.
+   */
+  fontSizeBaseLG: number
+  /**
+   * Base extra-large font size token.
+   * Ideal for third-level page titles.
+   * Can also be used for larger labels or captions within medium text.
+   */
+  fontSizeBaseXL: number
+  /**
+   * Base 2 times extra-large font size token.
+   * Typically used for second-level page titles.
+   */
+  fontSizeBaseX2L: number
+  /**
+   * Base 3 times extra-large font size token.
+   * Designed for first-level page titles.
+   * Can also be used for labels or captions within huge text.
+   */
+  fontSizeBaseX3L: number
+  /**
+   * Base 4 times extra-large font size token.
+   * Ideal for huge text labels and captions.
+   */
+  fontSizeBaseX4L: number
+  /**
+   * Base 5 times extra-large font size token.
+   * Use this size for enormous text elements like hero titles.
+   * It should be the largest font size in your interface.
+   */
+  fontSizeBaseX5L: number
+  /**
+   * Base none line height token.
+   * Use for elements with no line height, like buttons, badges, and tags.
+   */
+  lineHeightBaseNone: number
+  /**
+   * Base tight line height token.
+   * For compact text elements with closely packed lines.
+   */
+  lineHeightBaseTight: number
+  /**
+   * Base snug line height token.
+   * Ideal for compact text that still needs some breathing room.
+   */
+  lineHeightBaseSnug: number
+  /**
+   * Base normal line height token.
+   * Standard line height for most text elements.
+   * Use for general content in your interface.
+   */
+  lineHeightBaseNormal: number
+  /**
+   * Base relaxed line height token.
+   * Provides more space between lines.
+   * Ideal for body text or large blocks of content.
+   */
+  lineHeightBaseRelaxed: number
+  /**
+   * Base loose line height token.
+   * Very spacious and airy, great for large headings.
+   * Suitable for text elements that need a lot of breathing room.
+   */
+  lineHeightBaseLoose: number
+}
+export type ThemeContextProviderProps = PropsWithChildren<
+  Partial<ThemeContextValue>
+>
+export type ThemeContextProviderComponent =
+  FunctionComponent<ThemeContextProviderProps>

package/source/helpers/index.ts

@@ -0,0 +1,3 @@
+export { StorybookControl } from '@/helpers/storybook'
+export { renderStyle } from '@/helpers/style'
+export type { RenderStyleHelper } from '@/helpers/style'

package/source/helpers/storybook/constants/control.ts

@@ -0,0 +1,25 @@
+/**
+ * Storybook control type enum for control helper.
+ * Should be used to build control instead of literal values.
+ * Feel free to extend this enum with new control types if required.
+ */
+export const enum StorybookControlType {
+  SELECT = 'select',
+  TEXT = 'text',
+  NUMBER = 'number',
+}
+
+/**
+ * Storybook control undefined option.
+ * Optional enum controls are supposed to have undefined value option.
+ * This option is supposed to be mapped to undefined value in control mapping.
+ */
+export const STORYBOOK_CONTROL_UNDEFINED_OPTION = '-'
+
+/**
+ * Storybook control numeric enum flag.
+ * We pass this flag throug storybook inside control object.
+ * Allows to handle this flag later, inside decorator if we need.
+ */
+export const STORYBOOK_CONTROL_NUMERIC_ENUM_FLAG =
+  'isCreactiveStorybookNumericEnum'

package/source/helpers/storybook/constants/index.ts

@@ -0,0 +1 @@
+export * from './control'

package/source/helpers/storybook/control.spec.ts

@@ -0,0 +1,140 @@
+import type { StoryContext } from '@storybook/react'
+import { StorybookControl, modifyContextNumericEnumControls } from './control'
+
+describe('@/helpers/storybook/control', () => {
+  describe('from numeric enum con', () => {
+    it('creates control from numeric method', () => {
+      enum TestEnum {
+        A,
+        B,
+        C,
+      }
+      const testControl = StorybookControl.fromNumericEnum(
+        TestEnum as Record<keyof typeof TestEnum, TestEnum>
+      )
+      expect(testControl.control.isCreactiveStorybookNumericEnum).toEqual(true)
+      expect(testControl.control.type).toEqual('select')
+      expect(testControl.options).toEqual([TestEnum.A, TestEnum.B, TestEnum.C])
+      expect(testControl.defaultValue).toEqual(TestEnum.A)
+      expect(testControl.control.labels[TestEnum.A]).toEqual('A')
+      expect(testControl.control.labels[TestEnum.B]).toEqual('B')
+      expect(testControl.control.labels[TestEnum.C]).toEqual('C')
+    })
+
+    it('creates optional control from numeric enum ', () => {
+      enum TestEnum {
+        A,
+        B,
+        C,
+      }
+      const testControl = StorybookControl.fromNumericEnum(
+        TestEnum as Record<keyof typeof TestEnum, TestEnum>
+      )
+      expect(testControl.control.isCreactiveStorybookNumericEnum).toEqual(true)
+      expect(testControl.control.type).toEqual('select')
+      expect(testControl.options).toEqual([TestEnum.A, TestEnum.B, TestEnum.C])
+      expect(testControl.defaultValue).toEqual(TestEnum.A)
+      expect(testControl.control.labels[TestEnum.A]).toEqual('A')
+      expect(testControl.control.labels[TestEnum.B]).toEqual('B')
+      expect(testControl.control.labels[TestEnum.C]).toEqual('C')
+      expect(testControl.control.labels[undefined as number]).toEqual('-')
+    })
+  })
+
+  describe('for children control method', () => {
+    it('creates children control', () => {
+      const testControl = StorybookControl.forChildren()
+      expect(testControl.control.type).toEqual('text')
+      expect(testControl.defaultValue).toEqual(expect.any(String))
+    })
+  })
+
+  describe('modifying context numeric controls helper', () => {
+    it('modifies context with numeric enum controls', () => {
+      const testContext: Pick<StoryContext, 'argTypes' | 'args'> = {
+        argTypes: {
+          testField: {
+            control: {
+              isCreactiveStorybookNumericEnum: true,
+              type: 'select',
+              labels: {
+                0: 'A',
+                1: 'B',
+                2: 'C',
+              },
+            },
+            defaultValue: 0,
+            options: [0, 1, 2],
+            name: 'testField',
+          },
+        },
+        args: {
+          testField: '0',
+        },
+      }
+      const modifiedContext = modifyContextNumericEnumControls(
+        testContext as StoryContext
+      )
+      expect(modifiedContext.args.testField).toEqual(0)
+    })
+
+    it('handles undefined control label when provided as value', () => {
+      // Storybook passes this label as a value for some reason when select it.
+      // This only happens, when some value was selected before.
+      // Our helper also handles this case inside (modifies value to undefined).
+      const testContext: Pick<StoryContext, 'argTypes' | 'args'> = {
+        argTypes: {
+          testField: {
+            control: {
+              isCreactiveStorybookNumericEnum: true,
+              type: 'select',
+              labels: {
+                undefined: '-',
+                0: 'A',
+                1: 'B',
+                2: 'C',
+              },
+            },
+            defaultValue: undefined,
+            options: [undefined, 0, 1, 2],
+            name: 'testField',
+          },
+        },
+        args: {
+          testField: '-',
+        },
+      }
+      const modifiedContext = modifyContextNumericEnumControls(
+        testContext as StoryContext
+      )
+      expect(modifiedContext.args.testField).toEqual(undefined)
+    })
+
+    it('does nothing with controls without numeric enum flag', () => {
+      const testContext: Pick<StoryContext, 'argTypes' | 'args'> = {
+        argTypes: {
+          testField: {
+            control: {
+              type: 'select',
+              labels: {
+                0: 'A',
+                1: 'B',
+                2: 'C',
+              },
+            },
+            defaultValue: 0,
+            options: [0, 1, 2],
+            name: 'testField',
+          },
+        },
+        args: {
+          testField: '0',
+        },
+      }
+      const modifiedContext = modifyContextNumericEnumControls(
+        testContext as StoryContext
+      )
+      expect(modifiedContext.args.testField).toEqual('0')
+    })
+  })
+})

package/source/helpers/storybook/control.ts

@@ -0,0 +1,115 @@
+import { faker } from '@faker-js/faker'
+import type { Decorator, StoryContext } from '@storybook/react'
+import {
+  STORYBOOK_CONTROL_NUMERIC_ENUM_FLAG,
+  STORYBOOK_CONTROL_UNDEFINED_OPTION,
+  StorybookControlType,
+} from './constants'
+
+/**
+ * Modifies context arguments to handle numeric enum controls.
+ * Numeric enum values are passed as strings by storybook controls.
+ * Seems like this happens because of select control implementation.
+ * This method is exported for test here, but should not be exported ouside.
+ */
+export const modifyContextNumericEnumControls = (context: StoryContext) => {
+  const args = {
+    ...context.args,
+  }
+  for (const key of Object.keys(context.argTypes)) {
+    if (typeof context.argTypes[key] === 'object') {
+      const control = context.argTypes[key].control as {
+        // The only flag, we are interested in..
+        [STORYBOOK_CONTROL_NUMERIC_ENUM_FLAG]?: boolean
+        // We don't care about everything else inside this type..
+        [key: string | number | symbol]: unknown
+      }
+      if (control[STORYBOOK_CONTROL_NUMERIC_ENUM_FLAG]) {
+        if (typeof args[key] === 'string') {
+          args[key] =
+            args[key] === STORYBOOK_CONTROL_UNDEFINED_OPTION
+              ? undefined
+              : Number(args[key])
+        }
+      }
+    }
+  }
+  return {
+    ...context,
+    args,
+  }
+}
+
+/**
+ * Storybook control helpers.
+ * Collected into a single class for convenient import.
+ * Helps to build storybook control objects for components stories.
+ */
+export const StorybookControl = new (class {
+  /**
+   * Builds a story object form provided numeric enum.
+   * Numeric enum will be mapped to storybook select control.
+   *
+   * @param target - target numeric enum for control
+   * @param isOptional - whether control is optional
+   */
+  public fromNumericEnum(target: Record<string, number>, isOptional = false) {
+    const options = Object.values(target).filter(
+      (value) => !isNaN(Number(value))
+    )
+    const keys = Object.keys(target).filter((value) => isNaN(Number(value)))
+    if (isOptional) options.unshift(undefined)
+    const labels: Record<number, string> = {}
+    for (const key of keys) labels[target[key]] = key
+    labels[undefined as number] = STORYBOOK_CONTROL_UNDEFINED_OPTION
+    return {
+      control: {
+        // Passing flag to handle numeric enum inside decorator.
+        [STORYBOOK_CONTROL_NUMERIC_ENUM_FLAG]: true,
+        type: StorybookControlType.SELECT,
+        labels,
+      },
+      options,
+      defaultValue: options[0],
+    }
+  }
+
+  /**
+   * Builds a story object for numeric input control.
+   * Numeric input will be mapped to storybook number control.
+   *
+   * @param defaultValue - can be provided to set default value
+   */
+  public forNumber(defaultValue?: number) {
+    return {
+      control: {
+        type: StorybookControlType.NUMBER,
+      },
+      defaultValue,
+    }
+  }
+
+  /**
+   * Returns default children control.
+   * Keeps storybook control factory logic together.
+   * Also allows to avoid faker import in every story file.
+   */
+  public forChildren() {
+    return {
+      control: {
+        type: StorybookControlType.TEXT,
+      },
+      defaultValue: faker.lorem.words(2),
+    }
+  }
+
+  /**
+   * Returns decorator for storybook stories.
+   * This decorator should apply some context modifications.
+   */
+  public getDecorator(): Decorator {
+    return (Story, context) => {
+      return Story(modifyContextNumericEnumControls(context))
+    }
+  }
+})()

package/source/helpers/storybook/index.ts

@@ -0,0 +1 @@
+export { StorybookControl } from './control'

package/source/helpers/style/index.ts

@@ -0,0 +1,2 @@
+export { renderStyle } from './style'
+export type { RenderStyleHelper } from './style.types'

package/source/helpers/style/style.spec.web.ts

@@ -0,0 +1,20 @@
+import { Fragment, isValidElement } from 'react'
+import { renderStyle } from './style'
+
+describe('@/helpers/style', () => {
+  describe('rendering style element helper', () => {
+    it('renders style element for react fragment', () => {
+      const element = renderStyle(Fragment)
+      expect(isValidElement(element)).toBe(true)
+      expect(element.type).toEqual('style')
+      const style = element.props.dangerouslySetInnerHTML.__html
+      expect(style).toContain('display:')
+      expect(style).toContain('inline')
+      expect(style).toContain('inline-flex')
+      expect(style).toContain('flex')
+      expect(style).toContain('pointer-events:')
+      expect(style).toContain('auto')
+      expect(style).toContain('none')
+    })
+  })
+})

package/source/helpers/style/style.ts

@@ -0,0 +1,14 @@
+import { isValidElement } from 'react'
+import { AppRegistry } from 'react-native'
+import type { AppRegistry as WebAppRegistryType } from 'react-native-web'
+import type { RenderStyleHelper } from './style.types'
+
+export const renderStyle: RenderStyleHelper = (component, key = 'main') => {
+  // Converting types to be able to use web specific methods..
+  const WebAppRegistry = AppRegistry as unknown as WebAppRegistryType
+  WebAppRegistry.registerComponent(key, () => component)
+  // If someone use this function on native platform it will throw an error..
+  // Seems fine.. calling this function on native platform makes no sence..
+  const element = WebAppRegistry.getApplication(key, null).getStyleElement()
+  if (isValidElement(element)) return element
+}

package/source/helpers/style/style.types.ts

@@ -0,0 +1,14 @@
+import type { ComponentType, JSX } from 'react'
+
+/**
+ * Rendering style node (for web platform server side rendering) helper.
+ * Using this helper on native platform makes no sense and will throw an error!
+ * You are supposed to use it only for server side rendering.
+ *
+ * @see https://necolas.github.io/react-native-web/docs/rendering/
+ * @see https://docs.expo.dev/guides/using-nextjs/
+ */
+export type RenderStyleHelper = (
+  component: ComponentType,
+  key?: string
+) => JSX.Element

package/source/hooks/index.ts

@@ -0,0 +1 @@
+export { useThemeStyleSheet } from '@/hooks/use-theme-style-sheet'