@tailorkit/app 0.1.0-beta.2 → 0.1.0-beta.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailorkit/app",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",
@@ -8,7 +8,8 @@
     "directory": "packages/app"
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "type": "module",
   "imports": {
@@ -46,7 +47,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tailorkit/core": "0.1.0-beta.2",
+    "@tailorkit/core": "0.1.0-beta.3",
     "cosmiconfig": "^10.0.0",
     "vite": "^8.2.2",
     "zod": "^4.4.3"

package/src/builder/index.ts

@@ -0,0 +1,116 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { writeFile } from "node:fs/promises";
+import { build as viteBuild } from "vite";
+import { loadTailorKitConfig } from "../config/loader";
+import { assertSupportedPreactVersion } from "../preact-version";
+import { createTailorKitUploadManifest } from "./upload-manifest";
+
+export {
+  createTailorKitUploadManifest,
+  tailorkitUploadManifestSchema,
+  type TailorKitUploadManifest,
+} from "./upload-manifest";
+
+const preactExternal = /^preact(?:\/.*)?$/u;
+const preactPackageJson = "preact/package.json";
+const preactPackageJsonModuleId = "\0tailorkit-preact-package-json";
+
+export interface BuildAppOptions {
+  configPath?: string;
+  cwd?: string;
+  entry?: string;
+  mode?: string;
+  outDir?: string;
+  watch?: boolean;
+}
+
+export const buildApp = async (options: BuildAppOptions = {}): Promise<unknown> => {
+  const loaded = await loadTailorKitConfig(options.configPath, options.cwd);
+  const entry = options.entry ?? loaded.config.client?.entry ?? "./src/client.ts";
+  const outDir = options.outDir ?? loaded.config.build?.outDir ?? ".tailorkit";
+  const preactVersion = getInstalledPreactVersion(loaded.root);
+
+  assertSupportedPreactVersion(preactVersion);
+
+  const resolvedOutDir = path.resolve(loaded.root, outDir);
+  const result = await viteBuild({
+    build: {
+      emptyOutDir: true,
+      lib: {
+        entry: path.resolve(loaded.root, entry),
+        fileName: "client",
+        formats: ["es"],
+      },
+      outDir: resolvedOutDir,
+      watch: options.watch ? {} : null,
+      minify: "oxc",
+      rollupOptions: {
+        external: (id) =>
+          id !== preactPackageJson && id !== preactPackageJsonModuleId && preactExternal.test(id),
+        output: {
+          comments: {
+            annotation: false,
+            jsdoc: false,
+            legal: false,
+          },
+          minify: true,
+          minifyInternalExports: true,
+        },
+      },
+    },
+    configFile: false,
+    mode: options.mode,
+    plugins: [
+      {
+        name: "tailorkit-preact-package-json",
+        enforce: "pre",
+        resolveId(id) {
+          if (id === preactPackageJson) {
+            return preactPackageJsonModuleId;
+          }
+
+          return null;
+        },
+        load(id) {
+          if (id === preactPackageJsonModuleId) {
+            const version = JSON.stringify(preactVersion);
+
+            return `export const version = ${version}; export default { version: ${version} };`;
+          }
+
+          return null;
+        },
+      },
+    ],
+    root: loaded.root,
+  });
+
+  await writeFile(
+    path.join(resolvedOutDir, "tailorkit-upload.json"),
+    `${JSON.stringify(createTailorKitUploadManifest(), null, 2)}\n`,
+    "utf-8",
+  );
+
+  return result;
+};
+
+function getInstalledPreactVersion(root: string): string {
+  const require = createRequire(path.join(root, "package.json"));
+
+  try {
+    const packageJsonPath = require.resolve("preact/package.json");
+    const packageJson = require(packageJsonPath) as { version?: unknown };
+
+    if (typeof packageJson.version === "string") {
+      return packageJson.version;
+    }
+  } catch (error) {
+    throw new Error(
+      `TailorKit requires Preact to build an app. Install preact@^10 and try again.`,
+      { cause: error },
+    );
+  }
+
+  throw new Error("Unable to read the installed Preact version.");
+}

package/src/builder/upload-manifest.ts

@@ -0,0 +1,18 @@
+import { z } from "zod";
+
+export const tailorkitUploadManifestSchema = z.object({
+  assets: z.object({
+    client: z.literal("client.js"),
+  }),
+  version: z.literal(1),
+});
+
+export type TailorKitUploadManifest = z.output<typeof tailorkitUploadManifestSchema>;
+
+export const createTailorKitUploadManifest = (): TailorKitUploadManifest =>
+  tailorkitUploadManifestSchema.parse({
+    assets: {
+      client: "client.js",
+    },
+    version: 1,
+  });

package/src/config/config.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+const clientConfigSchema = z.object({
+  entry: z.string().default("./src/client.ts"),
+});
+
+const buildConfigSchema = z.object({
+  outDir: z.string().default(".tailorkit"),
+});
+
+const tailorkitConfigSchema = z.object({
+  appId: z.string().min(1).optional(),
+  build: buildConfigSchema.optional(),
+  client: clientConfigSchema.optional(),
+  host: z.string().url(),
+});
+
+export type TailorKitConfig = z.input<typeof tailorkitConfigSchema>;
+export type ResolvedTailorKitConfig = z.output<typeof tailorkitConfigSchema>;
+
+export { tailorkitConfigSchema };
+
+export const defineConfig = (config: TailorKitConfig): TailorKitConfig => config;
+export const defineTailorKitConfig = defineConfig;

package/src/config/index.ts

@@ -0,0 +1 @@
+export { defineConfig, defineTailorKitConfig, type TailorKitConfig } from "./config";

package/src/config/loader.ts

@@ -0,0 +1,35 @@
+import { cosmiconfig } from "cosmiconfig";
+import path from "node:path";
+import type { ResolvedTailorKitConfig } from "./config";
+import { tailorkitConfigSchema } from "./config";
+
+export interface LoadedTailorKitConfig {
+  config: ResolvedTailorKitConfig;
+  filepath: string;
+  root: string;
+}
+
+const explorer = cosmiconfig("tailorkit", {
+  searchPlaces: ["tailorkit.config.ts", "tailorkit.config.mjs", "tailorkit.config.js"],
+});
+
+export const loadTailorKitConfig = async (
+  configPath: string | undefined,
+  cwd = process.cwd(),
+): Promise<LoadedTailorKitConfig> => {
+  const searchFrom = path.resolve(cwd);
+  const result =
+    configPath === undefined
+      ? await explorer.search(searchFrom)
+      : await explorer.load(path.resolve(searchFrom, configPath));
+
+  if (result === null) {
+    throw new Error(`Could not find tailorkit config from ${searchFrom}.`);
+  }
+
+  return {
+    config: tailorkitConfigSchema.parse(result.config),
+    filepath: result.filepath,
+    root: path.dirname(result.filepath),
+  };
+};

package/src/index.ts

@@ -0,0 +1,206 @@
+import { createContext, h, render } from "preact";
+import type { ComponentChild, ComponentChildren, ComponentType, VNode } from "preact";
+import { useContext } from "preact/hooks";
+
+declare const __PREACT_VERSION__: string;
+
+const preactVersion = __PREACT_VERSION__;
+
+// oxlint-disable-next-line typescript-eslint/no-empty-interface, typescript-eslint/no-empty-object-type
+export interface TailorKitScreens {}
+
+export type ScreenPath = Extract<keyof TailorKitScreens & string, `/${string}`>;
+export type AppScreenPath = ScreenPath;
+
+export type ScreenProps<TPath extends ScreenPath> = TailorKitScreens[TPath] extends object
+  ? TailorKitScreens[TPath]
+  : Record<string, never>;
+
+export type ScreenPropsForPath<TPath extends AppScreenPath> = TPath extends ScreenPath
+  ? ScreenProps<TPath>
+  : never;
+
+export type ScreenContext<TPath extends AppScreenPath> =
+  ScreenPropsForPath<TPath> extends { context: infer TContext } ? TContext : Record<string, never>;
+
+export type View<TProps extends object = Record<string, never>> = (props: TProps) => ComponentChild;
+
+export type ScreenRuntimeProps<TPath extends AppScreenPath> =
+  | {
+      context: ScreenContext<TPath>;
+      screen: TPath;
+      status: "ready";
+    }
+  | {
+      context?: never;
+      screen: TPath;
+      status: "loading";
+    }
+  | {
+      context?: never;
+      screen: TPath;
+      status: "error";
+    };
+
+export interface ScreenDefinition<TPath extends AppScreenPath = AppScreenPath> {
+  component: View<ScreenRuntimeProps<TPath>>;
+  path: TPath;
+  useContext: () => ScreenContext<TPath>;
+}
+
+type RegisteredScreens = {
+  [TPath in AppScreenPath]: ScreenDefinition<TPath>;
+};
+
+type ScreenDefinitions = Partial<RegisteredScreens>;
+
+type InvalidScreenPath<TScreens> = Exclude<keyof TScreens & string, `/${string}`>;
+
+type RequireScreenPaths<TScreens> =
+  InvalidScreenPath<TScreens> extends never
+    ? unknown
+    : {
+        readonly __tailorkit_error__: `Screen paths must start with "/". Invalid screen: ${InvalidScreenPath<TScreens>}`;
+      };
+
+type ScreenKeyPathMismatch<TScreens> = {
+  [TPath in keyof TScreens & string]: TScreens[TPath] extends ScreenDefinition<infer TScreenPath>
+    ? TScreenPath extends TPath
+      ? never
+      : TPath
+    : TPath;
+}[keyof TScreens & string];
+
+type RequireMatchingScreenKeys<TScreens> =
+  ScreenKeyPathMismatch<TScreens> extends never
+    ? unknown
+    : {
+        readonly __tailorkit_error__: `Screen key must match createScreen path. Invalid screen: ${ScreenKeyPathMismatch<TScreens>}`;
+      };
+
+export interface TailorKitClient<TScreens extends ScreenDefinitions = ScreenDefinitions> {
+  screens: TScreens;
+}
+
+export interface TailorKitClientMeta {
+  preactVersion: string;
+}
+
+export interface TailorKitClientRuntime {
+  h: typeof h;
+  render: (vnode: VNode, parent: Element | Document | ShadowRoot | DocumentFragment) => void;
+}
+
+export type TailorKitClientWithMeta<TScreens extends ScreenDefinitions = ScreenDefinitions> =
+  TailorKitClient<TScreens> & {
+    $meta: TailorKitClientMeta;
+    $runtime: TailorKitClientRuntime;
+  };
+
+export const createScreen = <const TPath extends AppScreenPath>(
+  path: TPath,
+  options: {
+    component: View<Record<string, never>>;
+    error?: View<Record<string, never>>;
+    loading?: View<Record<string, never>>;
+  },
+): ScreenDefinition<TPath> => {
+  const Context = createContext<ScreenContext<TPath> | null>(null);
+
+  const Screen = (props: ScreenRuntimeProps<TPath>) => {
+    if (props.status === "loading") {
+      return options.loading ? h(options.loading as ComponentType<object>, {}) : null;
+    }
+
+    if (props.status === "error") {
+      return options.error ? h(options.error as ComponentType<object>, {}) : null;
+    }
+
+    return h(
+      Context.Provider,
+      { value: props.context as ScreenContext<TPath> },
+      h(options.component as ComponentType<object>, {}),
+    );
+  };
+
+  return {
+    component: Screen,
+    path,
+    useContext: () => {
+      const context = useContext(Context);
+
+      if (context === null) {
+        throw new Error(`Screen context is only available while rendering "${path}".`);
+      }
+
+      return context;
+    },
+  };
+};
+
+export const defineClient = <const TScreens extends ScreenDefinitions>(
+  client: TailorKitClient<TScreens> &
+    RequireScreenPaths<TScreens> &
+    RequireMatchingScreenKeys<TScreens>,
+): TailorKitClientWithMeta<TScreens> => ({
+  ...client,
+  $meta: {
+    preactVersion,
+  },
+  $runtime: {
+    h,
+    render,
+  },
+});
+
+const componentTagPrefix = "tailorkit-";
+
+const toComponentTagName = (name: string): string =>
+  `${componentTagPrefix}${name
+    .replaceAll(/([a-z0-9])([A-Z])/gu, "$1-$2")
+    .replaceAll(/[\s_]+/gu, "-")
+    .toLowerCase()}`;
+
+const toCallbackEventName = (name: string): string =>
+  `tailorkitcallback${name.replaceAll(/[^A-Za-z0-9_$]/gu, "").toLowerCase()}`;
+
+const toEventProp = (event: string): string => `on${event}`;
+
+export const createRemoteComponent = <TProps extends object, TSlots extends readonly string[]>(
+  name: string,
+  options: { callbacks?: Record<string, number>; slots: TSlots },
+): View<TProps & { children?: ComponentChildren }> => {
+  const tagName = toComponentTagName(name);
+  const callbacks = options.callbacks;
+
+  if (!callbacks || Object.keys(callbacks).length === 0) {
+    return function RemoteComponent({ children, ...props }) {
+      return h(tagName, props, children);
+    };
+  }
+
+  return function RemoteComponent({ children, ...props }) {
+    const nextProps = { ...props } as Record<string, unknown>;
+    const callbackMap: Record<string, { callback: string; inputCount: number }> = {};
+
+    for (const [key, inputCount] of Object.entries(callbacks)) {
+      const callback = nextProps[key];
+      Reflect.deleteProperty(nextProps, key);
+      if (typeof callback !== "function") {
+        continue;
+      }
+
+      const eventName = toCallbackEventName(key);
+      callbackMap[eventName] = { callback: key, inputCount };
+      nextProps[toEventProp(eventName)] = (event: { detail?: unknown[] }) => {
+        callback(...(event.detail ?? []).slice(0, inputCount));
+      };
+    }
+
+    if (Object.keys(callbackMap).length > 0) {
+      nextProps["data-tailorkit-callbacks"] = JSON.stringify(callbackMap);
+    }
+
+    return h(tagName, nextProps, children);
+  };
+};

package/src/preact-version.ts

@@ -0,0 +1,31 @@
+export const MINIMUM_PREACT_MAJOR_VERSION = 10;
+
+export interface PreactVersionCheck {
+  major: number;
+  version: string;
+}
+
+export const parsePreactVersion = (version: string): PreactVersionCheck => {
+  const match = /^(\d+)\./u.exec(version);
+
+  if (!match?.[1]) {
+    throw new Error(`Unable to parse Preact version "${version}".`);
+  }
+
+  return {
+    major: Number.parseInt(match[1], 10),
+    version,
+  };
+};
+
+export const assertSupportedPreactVersion = (version: string): PreactVersionCheck => {
+  const check = parsePreactVersion(version);
+
+  if (check.major < MINIMUM_PREACT_MAJOR_VERSION) {
+    throw new Error(
+      `TailorKit requires Preact ${MINIMUM_PREACT_MAJOR_VERSION}.0.0 or newer, but found ${version}.`,
+    );
+  }
+
+  return check;
+};