@boxcustodia/library 2.0.0-alpha.2 → 2.0.0-alpha.21

package/src/stores/theme.store.ts

@@ -0,0 +1,31 @@
+import { createStore, type StoreApi } from "zustand";
+import { Theme } from "../providers/theme/types";
+
+interface ThemeStore {
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+  getComponentProps: <TComponent extends keyof Theme, TProps>(
+    componentName: TComponent,
+    props: TProps,
+    defaultProps?: Partial<TProps>,
+  ) => TProps;
+}
+
+export type ThemeStoreApi = StoreApi<ThemeStore>;
+
+const createThemeStore = (initTheme: Theme = {}) => {
+  return createStore<ThemeStore>()((set, get) => ({
+    theme: initTheme,
+    setTheme: (theme) => set({ theme }),
+    getComponentProps: (componentName, props, defaultProps = {}) => {
+      const themeProps = get().theme[componentName] || {};
+      return {
+        ...defaultProps,
+        ...themeProps,
+        ...props,
+      };
+    },
+  }));
+};
+
+export { createThemeStore };

package/src/styles/components.css

@@ -0,0 +1,4 @@
+@import "tailwindcss/utilities";
+@import "tw-animate-css";
+@import "./theme.css";
+@source "../";

package/src/styles/index.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "./theme.css";

package/src/styles/library.css

@@ -0,0 +1,2 @@
+@import "./theme.css";
+@source "../src";

package/src/styles/theme.css

@@ -0,0 +1,232 @@
+@import "tw-animate-css";
+@custom-variant open (&[data-state="open"]);
+@custom-variant closed (&[data-state="closed"]);
+@custom-variant invalid (&[aria-invalid="true"]);
+
+@theme {
+  --color-background: oklch(100% 0 0);
+  --color-foreground: oklch(13.63% 0.036 259.2);
+
+  --color-popover: oklch(100% 0 0);
+  --color-popover-foreground: oklch(13.63% 0.036 259.2);
+
+  --color-primary: oklch(59.5% 0.195 270.48);
+  --color-primary-foreground: oklch(100% 0 0);
+
+  --color-secondary: oklch(96.83% 0.007 247.9);
+  --color-secondary-foreground: oklch(20.77% 0.04 265.75);
+
+  --color-muted: oklch(96.83% 0.007 247.9);
+  --color-muted-foreground: oklch(55.44% 0.041 257.42);
+
+  --color-accent: oklch(96.74% 0.001 286.38);
+  --color-accent-foreground: oklch(19.06% 0.003 247.96);
+
+  --color-error: oklch(63.68% 0.208 25.33);
+  --color-error-foreground: oklch(98.42% 0.003 247.86);
+
+  --color-success: oklch(70.1% 0.146 156.33);
+  --color-success-foreground: oklch(98.42% 0.003 247.86);
+
+  --color-warning: oklch(79.65% 0.16 70.08);
+  --color-warning-foreground: oklch(98.42% 0.003 247.86);
+
+  --color-info: oklch(62.8% 0.152 237.57);
+  --color-info-foreground: oklch(98.42% 0.003 247.86);
+
+  --animate-toast-bump: toast-bump 0.4s cubic-bezier(0.34, 1.56, 0.64, 1);
+  --animate-skeleton: skeleton 1.5s linear infinite;
+
+  --color-input: oklch(76.68% 0 0);
+  --color-checkbox: var(--color-primary);
+  --color-ring: oklch(13.63% 0.036 259.2);
+
+  --radius: 0.5rem;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: calc(var(--radius));
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-tag: 0.375rem;
+  --radius-checkbox: 0.25rem;
+
+  --icon-size: 1rem;
+
+  --z-overlay: 50;
+  --z-float: 60;
+  --z-toast: 70;
+}
+/* Tooltip enter animation — @starting-style is more reliable than data-[starting-style]
+   because it guarantees the browser paints the initial state before the transition fires,
+   avoiding the "no animation" issue caused by lost repaint frames. */
+@starting-style {
+  [data-slot="tooltip-popup"] {
+    scale: 0.98;
+    opacity: 0;
+  }
+}
+
+@layer base {
+  #root {
+    isolation: isolate;
+  }
+
+  body {
+    background-color: var(--color-background);
+    color: var(--color-foreground);
+  }
+  * {
+    box-sizing: border-box;
+    margin: 0;
+    padding: 0;
+  }
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-gray-200, currentColor);
+  }
+
+  input:disabled,
+  button:disabled,
+  textarea:disabled,
+  select:disabled,
+  [data-disabled="true"] {
+    pointer-events: none;
+    opacity: 0.5;
+  }
+  button:not(:disabled),
+  [role="button"]:not(:disabled) {
+    cursor: pointer;
+  }
+
+  .field-error {
+    border-color: var(--color-error);
+  }
+
+  .lucide {
+    width: var(--icon-size);
+    height: var(--icon-size);
+  }
+
+  @keyframes pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.9;
+    }
+  }
+
+  @keyframes fadeIn {
+    from {
+      opacity: 0;
+    }
+    to {
+      opacity: 1;
+    }
+  }
+
+  /* Btn loader */
+  .btn-loader-enter,
+  .btn-loader-exit {
+    overflow: hidden;
+  }
+
+  .btn-loader-enter {
+    width: 0;
+    opacity: 0;
+  }
+
+  .btn-loader-enter-active {
+    width: var(--icon-size);
+    opacity: 1;
+    transition:
+      width 0.3s ease,
+      opacity 0.3s ease;
+  }
+
+  .btn-loader-exit {
+    width: var(--icon-size);
+    opacity: 1;
+  }
+
+  .btn-loader-exit-active {
+    width: 0;
+    opacity: 0;
+    transition:
+      width 0.15s ease,
+      opacity 0.25s ease;
+  }
+
+  /* Fade */
+  .fade-enter {
+    opacity: 0;
+    transform: scale(0.8);
+  }
+
+  .fade-enter-active {
+    opacity: 1;
+    transform: scale(1);
+    transition:
+      opacity 0.1s ease,
+      transform 0.1s ease;
+  }
+
+  .fade-exit {
+    opacity: 1;
+    transform: scale(1);
+  }
+
+  .fade-exit-active {
+    opacity: 0;
+    transform: scale(0.8);
+    transition:
+      opacity 0.2s ease,
+      transform 0.2s ease;
+  }
+
+  @keyframes skeleton {
+    to {
+      background-position: -200% 0;
+    }
+  }
+
+  @keyframes toast-bump {
+    0%,
+    100% {
+      transform: scale(1);
+    }
+    40% {
+      transform: scale(1.03);
+    }
+  }
+
+  .numberInput {
+    /* Chrome, Safari, Edge, Opera */
+    &::-webkit-outer-spin-button,
+    &::-webkit-inner-spin-button {
+      -webkit-appearance: none;
+      margin: -1;
+    }
+
+    /* Firefox */
+    &[type="number"] {
+      -moz-appearance: textfield;
+    }
+  }
+
+  .space-y-6 > :not([hidden]) ~ :not([hidden]) {
+    margin-top: 1.5rem;
+  }
+  .space-y-4 > :not([hidden]) ~ :not([hidden]) {
+    margin-top: 1rem;
+  }
+  .space-y-2 > :not([hidden]) ~ :not([hidden]) {
+    margin-top: 0.5rem;
+  }
+  .space-y-1 > :not([hidden]) ~ :not([hidden]) {
+    margin-top: 0.275rem;
+  }
+}

package/src/utils/dates/parseDateRange.utility.ts

@@ -0,0 +1,39 @@
+import { isDate, parse } from "date-fns";
+import { DateRange } from "../../components";
+
+/**
+ * @typedef {Object} DateRange
+ * @property {Date} start - The start date of the range.
+ * @property {Date} end - The end date of the range.
+ */
+
+/**
+ * Parses a date range string in the format "DD/MM/YYYY - DD/MM/YYYY" and returns an object with start and end dates.
+ *
+ * @param {string} dateRange - The date range string to parse.
+ * @returns {DateRange} An object containing the start and end dates.
+ * @throws Will throw an error if the input string is not in the expected format or the dates are invalid.
+ */
+export const parseDateRange = (dateRange: string): DateRange => {
+  if (typeof dateRange !== "string") {
+    throw new Error("The date range must be a string.");
+  }
+
+  const parts = dateRange.split(" - ");
+  if (parts.length !== 2) {
+    throw new Error('The date range format must be "DD/MM/YYYY - DD/MM/YYYY".');
+  }
+
+  const [startDateString, endDateString] = parts;
+
+  const dateFormat = "dd/MM/yyyy";
+
+  const start = parse(startDateString, dateFormat, new Date());
+  const end = parse(endDateString, dateFormat, new Date());
+
+  if (!isDate(start) || !isDate(end)) {
+    throw new Error("One or both of the dates are invalid.");
+  }
+
+  return { start, end };
+};

package/src/utils/form.test.tsx

@@ -0,0 +1,143 @@
+import {
+  fireEvent,
+  render,
+  renderHook,
+  screen,
+  waitFor,
+} from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { z } from "zod";
+import { HookField, HookForm, parseFormValues, useHookForm } from "./form";
+
+// ─── parseFormValues ──────────────────────────────────────────────────────────
+
+describe("parseFormValues", () => {
+  const schema = z.object({
+    name: z.string().min(1, "required"),
+    age: z.coerce.number().min(0),
+  });
+
+  it("returns data and empty errors on valid input", () => {
+    const result = parseFormValues(schema, { name: "Alice", age: "30" });
+    expect(result.data).toEqual({ name: "Alice", age: 30 });
+    expect(result.errors).toEqual({});
+  });
+
+  it("returns null data and field errors on invalid input", () => {
+    const result = parseFormValues(schema, { name: "", age: "30" });
+    expect(result.data).toBeNull();
+    expect(result.errors.name).toBeDefined();
+    expect(result.errors.name.length).toBeGreaterThan(0);
+  });
+
+  it("captures multiple field errors simultaneously", () => {
+    const result = parseFormValues(schema, { name: "", age: -1 });
+    expect(result.data).toBeNull();
+    expect(result.errors.name).toBeDefined();
+    expect(result.errors.age).toBeDefined();
+  });
+});
+
+// ─── useHookForm ──────────────────────────────────────────────────────────────
+
+describe("useHookForm", () => {
+  it("returns a react-hook-form instance", () => {
+    const schema = z.object({ email: z.string().email() });
+    const { result } = renderHook(() => useHookForm(schema));
+    expect(result.current.handleSubmit).toBeTypeOf("function");
+    expect(result.current.register).toBeTypeOf("function");
+  });
+});
+
+// ─── HookForm ─────────────────────────────────────────────────────────────────
+
+const loginSchema = z.object({ username: z.string().min(1, "required") });
+
+function LoginForm({
+  onSubmit,
+}: {
+  onSubmit: (v: { username: string }) => void;
+}) {
+  const form = useHookForm(loginSchema);
+  return (
+    <HookForm form={form} onFormSubmit={onSubmit}>
+      <input {...form.register("username")} data-testid="username" />
+      <button type="submit">Submit</button>
+    </HookForm>
+  );
+}
+
+describe("HookForm", () => {
+  it("renders children", () => {
+    render(<LoginForm onSubmit={vi.fn()} />);
+    expect(screen.getByTestId("username")).toBeInTheDocument();
+  });
+
+  it("calls onFormSubmit with parsed values on valid submit", async () => {
+    const onSubmit = vi.fn();
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    fireEvent.change(screen.getByTestId("username"), {
+      target: { value: "alice" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: "Submit" }));
+
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledOnce());
+    expect(onSubmit).toHaveBeenCalledWith({ username: "alice" }, undefined);
+  });
+
+  it("does not call onFormSubmit on invalid submit", async () => {
+    const onSubmit = vi.fn();
+    render(<LoginForm onSubmit={onSubmit} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Submit" }));
+
+    await waitFor(() => expect(onSubmit).not.toHaveBeenCalled());
+  });
+});
+
+// ─── HookField ────────────────────────────────────────────────────────────────
+
+function FieldForm({ onSubmit }: { onSubmit: (v: { email: string }) => void }) {
+  const schema = z.object({ email: z.string().email("invalid email") });
+  const form = useHookForm(schema);
+  return (
+    <HookForm form={form} onFormSubmit={onSubmit}>
+      <HookField
+        name="email"
+        label="Email"
+        render={({ onChange, value, invalid }) => (
+          <input
+            data-testid="email"
+            data-invalid={invalid}
+            value={value}
+            onChange={onChange}
+          />
+        )}
+      />
+      <button type="submit">Submit</button>
+    </HookForm>
+  );
+}
+
+describe("HookField", () => {
+  it("renders the field input", () => {
+    render(<FieldForm onSubmit={vi.fn()} />);
+    expect(screen.getByTestId("email")).toBeInTheDocument();
+  });
+
+  it("exposes invalid=false initially", () => {
+    render(<FieldForm onSubmit={vi.fn()} />);
+    expect(screen.getByTestId("email").dataset.invalid).toBe("false");
+  });
+
+  it("marks invalid after failed submit", async () => {
+    render(<FieldForm onSubmit={vi.fn()} />);
+
+    fireEvent.click(screen.getByRole("button", { name: "Submit" }));
+
+    await waitFor(() =>
+      expect(screen.getByTestId("email").dataset.invalid).toBe("true"),
+    );
+  });
+});

package/src/utils/form.tsx

@@ -0,0 +1,131 @@
+import { zodResolver } from "@hookform/resolvers/zod";
+import type { ComponentProps, ReactNode } from "react";
+import {
+  Controller,
+  type ControllerRenderProps,
+  type FieldPath,
+  type FieldValues,
+  FormProvider,
+  type RegisterOptions,
+  useForm as rhfUseForm,
+  type SubmitHandler,
+  type UseFormProps,
+  type UseFormReturn,
+  useFormContext,
+} from "react-hook-form";
+import { z } from "zod";
+import { Field, type FieldProps, Form as LibraryForm } from "../components";
+
+/**
+ * Validates `formValues` from `Form.onFormSubmit` against a Zod schema and
+ * returns `{ data, errors }` ready to wire back into `Form`'s `errors` prop.
+ *
+ * - `data` is the typed, parsed value, or `null` when validation fails.
+ * - `errors` is the flattened `fieldErrors` object (empty on success).
+ *
+ * Value conventions worth knowing when writing the schema (these hold whether
+ * or not you use Zod):
+ * - `DateInput` and `DatePicker` submit an **ISO date string** (`yyyy-MM-dd`),
+ *   or `""` when empty. The format is locale-agnostic, sortable, and parseable
+ *   by `new Date()` or any backend without a custom parser. The displayed text
+ *   stays `dd/MM/yyyy` — display and value are different layers. To reformat,
+ *   it is a plain split: `iso.split("-").reverse().join("-")` → `dd-MM-yyyy`.
+ *   Avoid round-tripping through `new Date(iso)` + local getters (timezone
+ *   shift); split the string or use `parseISO`.
+ */
+export function parseFormValues<T extends z.ZodType>(
+  schema: T,
+  values: Record<string, unknown>,
+): { data: z.infer<T> | null; errors: Record<string, string[]> } {
+  const result = schema.safeParse(values);
+  if (result.success) {
+    return { data: result.data, errors: {} };
+  }
+  return {
+    data: null,
+    errors: z.flattenError(result.error).fieldErrors as Record<
+      string,
+      string[]
+    >,
+  };
+}
+
+export function useHookForm<T extends FieldValues = FieldValues>(
+  schema: z.ZodType<T>,
+  options?: Partial<UseFormProps<T>>,
+): UseFormReturn<T> {
+  return rhfUseForm<T>({
+    ...options,
+    resolver: zodResolver(schema as any),
+  });
+}
+
+type HookFormProps<T extends FieldValues> = Omit<
+  ComponentProps<typeof LibraryForm>,
+  "onSubmit" | "onFormSubmit" | "children"
+> & {
+  form: UseFormReturn<T>;
+  onFormSubmit: SubmitHandler<T>;
+  children: ReactNode;
+};
+
+export function HookForm<T extends FieldValues>({
+  form,
+  onFormSubmit,
+  children,
+  ...props
+}: HookFormProps<T>) {
+  return (
+    <FormProvider {...form}>
+      <LibraryForm
+        onSubmit={(event) => {
+          event.preventDefault();
+          form.handleSubmit(onFormSubmit)();
+        }}
+        {...props}
+      >
+        {children}
+      </LibraryForm>
+    </FormProvider>
+  );
+}
+
+export type HookFieldRenderProps<
+  T extends FieldValues = FieldValues,
+  TName extends FieldPath<T> = FieldPath<T>,
+> = ControllerRenderProps<T, TName> & {
+  invalid: boolean;
+};
+
+type HookFieldProps<
+  T extends FieldValues = FieldValues,
+  TName extends FieldPath<T> = FieldPath<T>,
+> = Omit<FieldProps, "children" | "error" | "render" | "name"> & {
+  name: TName;
+  rules?: RegisterOptions<T, TName>;
+  render: (field: HookFieldRenderProps<T, TName>) => ReactNode;
+};
+
+export function HookField<
+  T extends FieldValues = FieldValues,
+  TName extends FieldPath<T> = FieldPath<T>,
+>({ name, rules, render, ...fieldProps }: HookFieldProps<T, TName>) {
+  const { control } = useFormContext<T>();
+
+  return (
+    <Controller<T, TName>
+      name={name}
+      control={control}
+      rules={rules}
+      render={({ field, fieldState }) => (
+        <Field
+          {...fieldProps}
+          invalid={fieldState.invalid}
+          error={fieldState.error?.message}
+        >
+          {render({ ...field, invalid: fieldState.invalid })}
+        </Field>
+      )}
+    />
+  );
+}

package/src/utils/functions/createSafeContext.test.tsx

@@ -0,0 +1,37 @@
+import { renderHook } from "@testing-library/react";
+import React from "react";
+import { describe, expect, it } from "vitest";
+import { createSafeContext } from "./createSafeContext";
+
+describe("createSafeContext", () => {
+  it("returns a [useContext, Provider] tuple", () => {
+    const [useCtx, Provider] = createSafeContext<string>();
+    expect(typeof useCtx).toBe("function");
+    expect(Provider).toBeDefined();
+  });
+
+  it("throws when used outside a provider", () => {
+    const [useCtx] = createSafeContext<string>();
+    expect(() => renderHook(() => useCtx())).toThrow("Context value is null");
+  });
+
+  it("returns value when wrapped in provider", () => {
+    const [useCtx, Provider] = createSafeContext<string>();
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Provider value="hello">{children}</Provider>
+    );
+
+    const { result } = renderHook(() => useCtx(), { wrapper });
+    expect(result.current).toBe("hello");
+  });
+
+  it("returns object values correctly", () => {
+    const [useCtx, Provider] = createSafeContext<{ count: number }>();
+    const wrapper = ({ children }: { children: React.ReactNode }) => (
+      <Provider value={{ count: 42 }}>{children}</Provider>
+    );
+
+    const { result } = renderHook(() => useCtx(), { wrapper });
+    expect(result.current.count).toBe(42);
+  });
+});

package/src/utils/functions/createSafeContext.ts

@@ -0,0 +1,17 @@
+import React from "react";
+
+export const createSafeContext = <T>() => {
+  const context = React.createContext<T | null>(null);
+
+  const useContext = () => {
+    const contextValue = React.useContext(context);
+
+    if (contextValue === null) {
+      throw new Error("Context value is null");
+    }
+
+    return contextValue;
+  };
+
+  return [useContext, context.Provider] as const;
+};

package/src/utils/functions/ensureReactElement.test.tsx

@@ -0,0 +1,49 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ensureReactElement } from "./ensureReactElement";
+
+describe("ensureReactElement", () => {
+  it("wraps a string in the default div", () => {
+    const el = ensureReactElement({ children: "hello" });
+    render(el);
+    expect(screen.getByText("hello").tagName).toBe("DIV");
+  });
+
+  it("returns a valid ReactElement as-is", () => {
+    const child = <span data-testid="span">content</span>;
+    const el = ensureReactElement({ children: child });
+    render(el);
+    expect(screen.getByTestId("span")).toBeInTheDocument();
+  });
+
+  it("calls a render function with props and returns the result", () => {
+    const renderFn = (props: { label: string }) => (
+      <span data-testid="fn-result">{props.label}</span>
+    );
+    const el = ensureReactElement({
+      children: renderFn,
+      props: { label: "from-fn" },
+    });
+    render(el);
+    expect(screen.getByTestId("fn-result")).toHaveTextContent("from-fn");
+  });
+
+  it("wraps a number in the default div", () => {
+    const el = ensureReactElement({ children: 42 as any });
+    render(el);
+    expect(screen.getByText("42").tagName).toBe("DIV");
+  });
+
+  it("uses custom wrapper element via as prop", () => {
+    const el = ensureReactElement({ children: "text", as: "section" });
+    render(el);
+    expect(screen.getByText("text").tagName).toBe("SECTION");
+  });
+
+  it("wraps in fallback when render fn returns non-element (null)", () => {
+    const renderFn = () => null as any;
+    const el = ensureReactElement({ children: renderFn, as: "span" });
+    const { container } = render(el);
+    expect(container.querySelector("span")).toBeInTheDocument();
+  });
+});