southpaw 0.2.7

package/modules/component.tsx

@@ -0,0 +1,483 @@
+/* TODO: Refactor typings */
+import {
+  FunctionComponent,
+  RefObject,
+  ReactNode,
+  ReactElement,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef,
+  useState,
+  createRef,
+  memo,
+  cloneElement,
+} from "react";
+import ObservableSlim from "./state";
+import isEqual from "react-fast-compare";
+import { _ErrorBoundary } from "./error";
+import { NextRouter, useRouter } from "next/router";
+import { ComboboxData, SegmentedControlItem } from "@mantine/core";
+import { CommonProps, MOUNT_ANIMATIONS } from "../ui/props";
+
+type PropsType<T = Record<string, unknown>> = CommonProps & T;
+type StateType = Record<string, unknown>;
+type RefsType = Record<string, unknown>;
+type PropDef = {
+  label: string;
+} & (
+  | {
+      type: "color";
+    }
+  | {
+      type: "number";
+      min?: number;
+      max?: number;
+      step?: number;
+    }
+  | {
+      type: "size";
+      min?: number;
+      max?: number;
+      step?: number;
+    }
+  | {
+      type: "icon";
+    }
+  | {
+      type: "segmented";
+      options: SegmentedControlItem[];
+    }
+  | {
+      type: "select";
+      options: ComboboxData;
+    }
+  | {
+      type: "switch";
+    }
+  | {
+      type: "text";
+      multiline?: boolean;
+    }
+  | {
+      type: "list-text";
+    }
+  | {
+      type: "list-json";
+    }
+  | {
+      type: "action";
+    }
+);
+export type PropsDef = Record<string, PropDef>;
+
+type ComputedType<P, S> = Record<
+  string,
+  (
+    this: {
+      computed: any;
+      state: S;
+      props: P;
+      router: NextRouter;
+      el: HTMLElement | null;
+    },
+    ...args: unknown[]
+  ) => unknown
+>;
+
+type MethodsType<P, S, C extends ComputedType<P, S>, R> = Record<
+  string,
+  (
+    this: {
+      state: S;
+      props: P;
+      computed: {
+        [KC in keyof C]: ReturnType<C[KC]>;
+      };
+      refs: {
+        [K in keyof R]: {
+          current: R[K];
+        };
+      };
+      methods: Record<string, (...args: any[]) => any>;
+      router: NextRouter;
+      devError: (error: ReactElement) => void;
+      el: HTMLElement | null;
+    },
+    ...args: any[]
+  ) => any
+>;
+
+type RenderThisType<
+  P,
+  S,
+  C extends ComputedType<P, S>,
+  R,
+  M extends MethodsType<P, S, C, R>,
+> = {
+  methods: { [K in keyof M]: (...args: Parameters<M[K]>) => ReturnType<M[K]> };
+  state: S;
+  props: P & { mount_animation?: any };
+  refs: { [K in keyof R]: RefObject<R[K]> };
+  router: NextRouter;
+  computed: {
+    [KC in keyof C]: ReturnType<C[KC]>;
+  };
+  devError: (error: ReactElement) => void;
+  el: HTMLElement | null;
+};
+
+export interface ComponentParams<
+  P = PropsType,
+  S = StateType,
+  C extends ComputedType<P, S> = ComputedType<P, S>,
+  R = RefsType,
+  M extends MethodsType<P, S, C, R> = MethodsType<P, S, C, R>,
+> {
+  name: string;
+  description: string;
+  props?: P;
+  propsDef?: PropsDef;
+  state?: S;
+  refs?: R;
+  methods?: M;
+  computed?: C;
+  lifecycle?: {
+    onMount?: (this: RenderThisType<P, S, C, R, M>) => void;
+    onDomMutation?: (
+      this: RenderThisType<P, S, C, R, M>,
+      mutation: MutationRecord,
+    ) => void;
+    onUnmount?: (this: RenderThisType<P, S, C, R, M>) => void;
+    onRender?: (this: RenderThisType<P, S, C, R, M>) => void;
+    onMountAnimationEnd?: (this: RenderThisType<P, S, C, R, M>) => void;
+    onRouterReady?: (this: RenderThisType<P, S, C, R, M>) => void;
+    onPropChange?: (
+      this: RenderThisType<P, S, C, R, M>,
+      propName: keyof P,
+      previousProp: unknown,
+      currentProp: unknown,
+    ) => void;
+  };
+  render: (this: RenderThisType<P, S, C, R, M>) => ReactNode;
+}
+
+export type ComponentReturnType<P> = FunctionComponent<P> & {
+  // Optional metadata used by the Southpaw dev tools
+  params?: ComponentParams<P, any, any, any, any>;
+};
+
+export const create_component = <
+  P = PropsType,
+  S = StateType,
+  C extends ComputedType<P, S> = ComputedType<P, S>,
+  R = RefsType,
+  M extends MethodsType<P, S, C, R> = MethodsType<P, S, C, R>,
+>(
+  _params: ComponentParams<P, S, C, R, M>,
+): ComponentReturnType<P> => {
+  const params = _params;
+  params.propsDef = params.propsDef || {};
+  const defaultMountAnimation = {
+    mount_animation: MOUNT_ANIMATIONS.fade,
+  };
+  const Fn = memo((_props: P) => {
+    const ref = useRef<HTMLDivElement>(null);
+    const router = useRouter();
+    const [errorHtml, setErrorHtml] = useState("");
+    const defaultProps = (params.props || {}) as P;
+    const el = ref.current;
+
+    const props = {
+      ...defaultMountAnimation,
+      ...defaultProps,
+      ...(_props || {}),
+    } as P;
+
+    const refs = useMemo(
+      () =>
+        Object.keys(params.refs || {}).reduce(
+          (acc, refName) => {
+            acc[refName] = createRef();
+            return acc;
+          },
+          {} as Record<string, ReturnType<typeof createRef>>,
+        ),
+      [],
+    );
+    const propsRef = useRef<Record<string, unknown>>(
+      props as unknown as Record<string, unknown>,
+    );
+    const [, forceUpdate] = useReducer((x) => x + 1, 0);
+    const state = useMemo(() => {
+      return ObservableSlim.create(
+        JSON.parse(JSON.stringify(params.state || {})),
+        true,
+        function () {
+          forceUpdate();
+        },
+      );
+    }, []);
+
+    const devError = (error: ReactElement) => {
+      import("react-dom/server").then(({ renderToString }) => {
+        setErrorHtml(renderToString(error));
+      });
+    };
+
+    const computed = Object.keys(
+      (params.computed || {}) as Record<string, unknown>,
+    ).reduce(
+      (acc, computedName) => {
+        const computedFn = (
+          params.computed as Record<
+            string,
+            (this: {
+              state: S;
+              props: P;
+              router: NextRouter;
+              el: HTMLElement | null;
+              computed: any;
+            }) => unknown
+          >
+        )[computedName];
+
+        if (typeof computedFn === "function") {
+          // Runtime binding – types are validated at the edge of ComponentParams
+          acc[computedName as keyof C] = computedFn.bind({
+            state: state as unknown as S,
+            props,
+            router,
+            el,
+            computed: acc,
+          })() as ReturnType<C[keyof C]>;
+        }
+
+        return acc;
+      },
+      {} as { [KC in keyof C]: ReturnType<C[KC]> },
+    );
+
+    const methods = Object.keys(
+      (params.methods || {}) as Record<string, unknown>,
+    ).reduce(
+      (acc, methodName) => {
+        const method = (
+          params.methods as Record<string, (...args: any[]) => any>
+        )[methodName];
+
+        if (typeof method === "function") {
+          // Runtime binding – types are validated at the edge of ComponentParams
+          (acc as Record<string, (...args: any[]) => any>)[methodName] =
+            method.bind({
+              state,
+              props,
+              computed,
+              refs,
+              router,
+              methods: acc,
+              devError,
+              el,
+            });
+        }
+
+        return acc;
+      },
+      {} as Record<string, (...args: any[]) => any>,
+    ) as {
+      [K in keyof M]: (...args: Parameters<M[K]>) => ReturnType<M[K]>;
+    };
+
+    useEffect(() => {
+      const lifecycleBindings = {
+        methods,
+        state,
+        computed,
+        props,
+        refs,
+        router,
+        el,
+      };
+      (
+        params.lifecycle?.onMount as
+          | ((this: typeof lifecycleBindings) => void)
+          | undefined
+      )?.bind(lifecycleBindings)();
+      return () => {
+        (
+          params.lifecycle?.onUnmount as
+            | ((this: typeof lifecycleBindings) => void)
+            | undefined
+        )?.bind(lifecycleBindings)();
+      };
+    }, []);
+
+    useEffect(() => {
+      const previousProps = propsRef.current;
+      const currentProps = props as unknown as Record<string, unknown>;
+      for (const propName of Object.keys(currentProps)) {
+        const previousProp = previousProps[propName];
+        const currentProp = currentProps[propName];
+        if (!isEqual(previousProp, currentProp)) {
+          const lifecycleBindings = {
+            methods,
+            state,
+            computed,
+            props,
+            refs,
+            router,
+            devError,
+            el,
+          };
+          (
+            params.lifecycle?.onPropChange as
+              | ((
+                  this: typeof lifecycleBindings,
+                  propName: string,
+                  previousProp: unknown,
+                  currentProp: unknown,
+                ) => void)
+              | undefined
+          )?.bind(lifecycleBindings)(propName, previousProp, currentProp);
+          propsRef.current[propName] = currentProp;
+        }
+      }
+    }, [props]);
+
+    useEffect(() => {
+      setTimeout(() => {
+        const lifecycleBindings = {
+          methods,
+          state,
+          computed,
+          props,
+          el,
+        };
+        (
+          params.lifecycle?.onRender as
+            | ((this: typeof lifecycleBindings) => void)
+            | undefined
+        )?.bind(lifecycleBindings)();
+      }, 25);
+    }, []);
+
+    useEffect(() => {
+      if (router.isReady) {
+        const lifecycleBindings = {
+          methods,
+          state,
+          computed,
+          props,
+          el,
+        };
+        (
+          params.lifecycle?.onRouterReady as
+            | ((this: typeof lifecycleBindings) => void)
+            | undefined
+        )?.bind(lifecycleBindings)();
+      }
+    }, [router.isReady]);
+
+    const mutationCallback: MutationCallback = (mutationList) => {
+      const lifecycleBindings = {
+        methods,
+        state,
+        computed,
+        props,
+        refs,
+        router,
+        el,
+      };
+      for (const mutation of mutationList) {
+        (
+          params.lifecycle?.onDomMutation as
+            | ((
+                this: typeof lifecycleBindings,
+                mutation: MutationRecord,
+              ) => void)
+            | undefined
+        )?.bind(lifecycleBindings)(mutation);
+      }
+    };
+
+    useEffect(() => {
+      const observer = new MutationObserver(mutationCallback);
+      if (ref.current instanceof HTMLElement) {
+        observer.observe(ref.current, {
+          attributes: true,
+          childList: true,
+          subtree: true,
+        });
+        const propsWithAnimation = props as P & CommonProps;
+        if (propsWithAnimation.mount_animation) {
+          let animation: Animation;
+          switch (typeof propsWithAnimation.mount_animation) {
+            case "string": {
+              const def = MOUNT_ANIMATIONS[propsWithAnimation.mount_animation];
+              animation = ref.current.animate(
+                def.keyframes as unknown as PropertyIndexedKeyframes,
+                def.options,
+              );
+              break;
+            }
+
+            default:
+              animation = ref.current.animate(
+                propsWithAnimation.mount_animation.keyframes,
+                propsWithAnimation.mount_animation.options,
+              );
+              break;
+          }
+          animation.onfinish = () => {
+            const lifecycleBindings = {
+              methods,
+              state,
+              computed,
+              props,
+              refs,
+              router,
+              el,
+            };
+            (
+              params.lifecycle?.onMountAnimationEnd as
+                | ((this: typeof lifecycleBindings) => void)
+                | undefined
+            )?.bind(lifecycleBindings)();
+          };
+        }
+      }
+      return () => {
+        observer.disconnect();
+      };
+    }, [ref]);
+
+    const bindings = {
+      methods,
+      state,
+      computed,
+      props,
+      refs,
+      router,
+      devError,
+      el,
+    };
+
+    const render = params.render.bind(
+      bindings as RenderThisType<P, S, C, R, M>,
+    ) as FunctionComponent<P>;
+    if (errorHtml) {
+      return <_ErrorBoundary errorHtml={errorHtml} />;
+    }
+    const jsx = render(props);
+    if (!jsx) {
+      return null;
+    }
+    return jsx;
+    return cloneElement(jsx as ReactElement, {
+      ref,
+    });
+  }) as ComponentReturnType<P>;
+  Fn.displayName = params.name;
+  Fn.params = params;
+  return Fn;
+};

package/modules/config/index.ts

@@ -0,0 +1,8 @@
+import { NextConfig } from "next";
+
+export const create_config = (): NextConfig => {
+  return {
+    reactStrictMode: false,
+    devIndicators: false,
+  };
+};

package/modules/database.ts

@@ -0,0 +1,25 @@
+import Dexie, { Table } from "dexie";
+
+type StoresType = Record<string, Record<string, unknown>>;
+type Params<S extends StoresType> = {
+  name: string;
+  version: number;
+  stores: {
+    [K in keyof S]: Array<keyof S[K]>;
+  };
+};
+export const create_database = <S extends StoresType>(params: Params<S>) => {
+  const db = new Dexie(params.name) as Dexie & { [K in keyof S]: Table<S[K]> };
+  const stores = Object.keys(params.stores).reduce(
+    (acc, storeName) => {
+      acc[storeName as keyof S] = ["++id", ...params.stores[storeName]].join(
+        ","
+      );
+      return acc;
+    },
+    {} as Record<keyof S, string>
+  );
+  db.version(params.version).stores(stores);
+  db.open();
+  return db;
+};

package/modules/document.tsx

@@ -0,0 +1,23 @@
+/* eslint-disable @next/next/no-page-custom-font */
+/* eslint-disable @next/next/google-font-display */
+import { ColorSchemeScript } from "@mantine/core";
+// eslint-disable-next-line @next/next/no-document-import-in-page
+import { Html, Head, Main, NextScript } from "next/document";
+
+export const create_document = () => {
+  const Fn = () => {
+    return (
+      <Html lang="en">
+        <Head>
+          <ColorSchemeScript defaultColorScheme="auto" />
+        </Head>
+        <body>
+          <Main />
+          <NextScript />
+        </body>
+      </Html>
+    );
+  };
+  Fn.displayName = "Document";
+  return Fn;
+};

package/modules/error.tsx

@@ -0,0 +1,16 @@
+export const _ErrorBoundary = ({ errorHtml }: { errorHtml: string }) => {
+  return (
+    <div
+      style={{
+        width: "100%",
+        height: "100%",
+        padding: 20,
+        boxShadow: "inset 0px 0px 0px 5px rgba(255,0,0,0.5)",
+        background: "rgba(255,0,0,0.1)",
+        fontFamily: "monospace",
+        fontWeight: "bolder",
+      }}
+      dangerouslySetInnerHTML={{ __html: errorHtml }}
+    />
+  );
+};

package/modules/page/autozoom.tsx

@@ -0,0 +1,92 @@
+import React, { useRef, useState, useEffect, ReactNode } from "react";
+
+interface AutoZoomContainerProps {
+  children: ReactNode;
+  initialScale?: number;
+  maxScale?: number;
+  step?: number;
+}
+
+export const AutoZoomContainer: React.FC<AutoZoomContainerProps> = ({
+  children,
+  initialScale = 0.05,
+  maxScale = 1,
+  step = 0.05,
+}) => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const childRef = useRef<HTMLDivElement>(null);
+  const [scale, setScale] = useState<number>(initialScale);
+
+  const checkFitAndAdjust = () => {
+    const container = containerRef.current;
+    const child = childRef.current;
+
+    if (!container || !child) return;
+
+    const containerRect = container.getBoundingClientRect();
+    const childRect = child.getBoundingClientRect();
+
+    // Add tolerance to prevent oscillation
+    const tolerance = 2; // pixels
+    const widthFits = childRect.width <= containerRect.width + tolerance;
+    const heightFits = childRect.height <= containerRect.height + tolerance;
+    const fits = widthFits && heightFits;
+
+    // Calculate how much we're overflowing (if at all)
+    const widthRatio = containerRect.width / childRect.width;
+    const heightRatio = containerRect.height / childRect.height;
+    const minRatio = Math.min(widthRatio, heightRatio);
+
+    if (!fits && scale > initialScale) {
+      // Content doesn't fit, zoom out - but use calculated ratio for better convergence
+      const targetScale = Math.max(scale * minRatio * 0.95, initialScale); // 0.95 for safety margin
+      setScale(targetScale);
+    } else if (fits && scale < maxScale) {
+      // Content fits, try to zoom in more gradually
+      const nextScale = Math.min(scale + step, maxScale);
+      // But don't zoom in if we're very close to not fitting
+      if (minRatio > 1.1) {
+        // Only zoom in if we have comfortable margin
+        setScale(nextScale);
+      }
+    }
+  };
+
+  useEffect(() => {
+    // Initial check after mount
+    const timeoutId = setTimeout(checkFitAndAdjust, 0);
+    return () => clearTimeout(timeoutId);
+  }, []);
+
+  useEffect(() => {
+    // React to scale change
+    const id = requestAnimationFrame(checkFitAndAdjust);
+    return () => cancelAnimationFrame(id);
+  }, [scale]);
+
+  return (
+    <div
+      ref={containerRef}
+      style={{
+        width: "100%",
+        height: "100%",
+        overflow: "hidden",
+        position: "relative",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <div
+        ref={childRef}
+        style={{
+          zoom: scale,
+          transformOrigin: "top left",
+          display: "inline-block",
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+};