@kwantis-id3/frontend-library 0.13.6 → 0.14.0

package/README.md

@@ -35,12 +35,12 @@ At the moment, the library contains the following components:
 - Button
 - Select (both single and multi)
 - Slider
+- Textfield
 
 The following are under development or on our roadmap:
 - Label
 - Checkbox
 - Radio
-- Textfield
 - Datepicker
 - Timepicker
 - Datetimepicker
@@ -51,10 +51,10 @@ The following are under development or on our roadmap:
 
 You can find various examples of usage in the projects stories.
 
-### Theming
+## Theming
 The library internally uses the [emotion](https://emotion.sh/docs/introduction) library for styling. By default, the library uses a default theme, that looks like this:
 
-```js
+```ts
 export const defaultThemeColors = {
   primary: { main: "#1d4e89", contrastText: "#ffffff" },
   secondary: { main: "#00b2ca", contrastText: "#ffffff" },
@@ -67,7 +67,7 @@ export const defaultThemeColors = {
 ```
 
 You can override the default theme by passing a custom theme to the `ThemeContextProvider` component, like this:
-```js
+```ts
 import { ThemeContextProvider } from "@kwantis-id3/frontend-library";
 
 const customTheme = {
@@ -91,7 +91,7 @@ const App = () => {
 
 To add custom properties to the theme, you can extend the `ThemeColorsObject` interface in a **.d.ts** file, like this:
 
-```js
+```ts
 import "@kwantis-id3/frontend-library";
 
 declare module "@kwantis-id3/frontend-library" {
@@ -102,11 +102,58 @@ declare module "@kwantis-id3/frontend-library" {
 }
 ```
 
-### The Color prop
+## The useThemeContext hook
+The library exports a `useThemeContext` hook, that can be used to access the theme object from any component,
+exposing a `ThemeProperties` object.
+
+```ts
+import { useThemeContext } from "@kwantis-id3/frontend-library";
+
+const MyComponent = () => {
+  const theme = useThemeContext();
+
+  useEffect(() => {
+    console.log(theme);
+  }, [theme]);
+
+  return <div>...</div>;
+};
+```
+
+Through the `ThemeProperties` object, you can access the theme colors either directly, or through the `getColor(color: string) => Color` property,
+that will return a valid Color based on the string parameter that it’s passed to it.
+
+```ts
+const theme = useThemeContext();
+const primaryColor = theme.colors.primary.main;
+// or
+const primaryColor = theme.getColor("primary");
+```
+
+Basically, the property `getColor` can recognise if you are passing a key of the theme, and return it’s corresponding object, or if you are passing it a hex string, or a rgb string, and so on.
+
+In the latter case, the contrastText property will automatically be generated to grant the best readability possible.
+
+If the passed string is not a valid color, the function will default to the primary color of the theme.
+```ts
+  const tertiartyColor = theme.getColor("tertiary");
+  console.log(tertiaryColor); // { main: "#7dcfb6", contrastText: "#ffffff" }
+
+  const fuchsia = theme.getColor("fuchsia");
+  console.log(fuchsia); // { main: "fuchsia", contrastText: "#000000" }
+
+  const rgba = theme.getColor("rgba(130, 146, 9, 0.5)");
+  console.log(rgba); // { main: "rgba(130, 146, 9, 0.4)", contrastText: "#000000" }
+
+  const notValid= theme.getColor("whatever123");
+  console.log(notValid); // { main: "#1d4e89", contrastText: "#ffffff" }
+```
+
+## The Color prop
 Each component that has a **color** prop, accepts a string.
 The string can be a color name, a hex code, or a css color function.
 
-```js
+```tsx
 // Color name
 <Button color="primary" />
 
@@ -117,3 +164,39 @@ The string can be a color name, a hex code, or a css color function.
 <Button color="rgb(29, 78, 137)" />
 ```
 
+## The styled utility and transientOptions
+The library exports a `styled` utility, that can be used to create styled components.
+It works exactly like the `styled` utility from the `@emotion/styled` library, but it automatically passes the theme to the component.
+
+```tsx
+import { styled } from "@kwantis-id3/frontend-library";
+
+const StyledButton = styled.button`
+  background-color: ${(props) => props.theme.colors.primary.main};
+  color: ${(props) => props.theme.colors.primary.contrastText};
+`;
+
+const MyComponent = () => {
+  return <StyledButton>Click me!</StyledButton>;
+};
+```
+
+It also automatically updated if the Theme interface is extended, so you don’t have to worry about updating it manually.
+
+If you want to create a styled component with props, you can do so using the `transientOptions` utility, like this:
+
+```tsx
+import { styled, transientOptions } from "@kwantis-id3/frontend-library";
+
+export const StyledDiv = styled("div", transientOptions)<{
+  $bgColor: string;
+}>`
+  background: ${(props) => props.$bgColor};
+`;
+
+const MyComponent = () => {
+  return <StyledDiv $bgColor="red">I'm red!</StyledDiv>;
+};
+```
+It's important that the props defined this way are prefixed with a `$` sign, to avoid conflicts.
+