@upstart.gg/sdk 0.0.96 → 0.0.97

package/src/shared/bricks/props/helpers.ts

@@ -0,0 +1,101 @@
+/**
+ * Helper functions for defining and working with props and groups of props
+ */
+import { type TProperties, Type, type TSchema, type TObject, type ObjectOptions } from "@sinclair/typebox";
+import { commonProps } from "./common";
+import type { PartialBy, Prop, PropGroup, GroupMetadata } from "./types";
+import { get } from "lodash-es";
+
+function isTObject(schema: TSchema | TProperties): schema is TObject {
+  return schema.type === "object";
+}
+
+export function group<T extends TProperties>({
+  title,
+  children,
+  category = "settings",
+  metadata,
+  options,
+}: PartialBy<PropGroup<T>, "category">) {
+  // check if children is already a TObject
+  if (isTObject(children)) {
+    const generated = Type.Composite([Type.Object({}), children], {
+      title,
+      metadata: {
+        category,
+        group: true,
+        ...metadata,
+      },
+      ...options,
+    });
+    return generated;
+  }
+
+  // Create the TypeBox schema with title as a standard property and group-specific info in metadata
+  return Type.Object(children, {
+    title,
+    ...options,
+    metadata: {
+      category,
+      group: true,
+      ...metadata,
+    },
+  });
+}
+
+export function prop<T extends TSchema>({ schema, ...rest }: Prop<T>): T {
+  Object.assign(schema, rest);
+  return schema;
+}
+
+// Functions to extract metadata from schemas
+export function getGroupInfo(schema: TSchema) {
+  const meta = schema.metadata as GroupMetadata;
+  return {
+    title: (schema.title ?? schema.metadata?.title) as string | undefined,
+    meta,
+    tab: meta.groupTab || "common",
+  };
+}
+
+export function defineProps<P extends TProperties>(props: P, options?: ObjectOptions) {
+  const finalProps = { ...commonProps, ...props };
+  return Type.Object(finalProps, options);
+}
+
+export const optional = Type.Optional;
+export const array = Type.Array;
+
+export type PropertyPath = string;
+export type StyleId = string;
+
+// Helper function to traverse a schema and filter to get style properties
+// (properties whose "ui:styleId" starts with "#styles:") and return them as an object with the path to the property
+// as the key and the $id as the value. Paths should be dot-separated.
+// The initial schema is a TObject, but nested schemas can be any type and arrays.
+export function getStyleProperties(schema: TSchema, path = "", styles: Record<PropertyPath, StyleId> = {}) {
+  if (schema.type === "object") {
+    for (const key in schema.properties) {
+      const prop = schema.properties[key];
+      if (prop["ui:styleId"]) {
+        styles[`${path}${key}`] = prop["ui:styleId"];
+      }
+      getStyleProperties(prop, `${path}${key}.`, styles);
+    }
+  } else if (schema.type === "array") {
+    getStyleProperties(schema.items, `${path}[].`, styles);
+  }
+  return styles;
+}
+
+export function getStyleValueById<T>(
+  stylePos: ReturnType<typeof getStyleProperties>,
+  formData: Record<string, unknown>,
+  id: string,
+) {
+  for (const [stylePath, styleId] of Object.entries(stylePos)) {
+    if (styleId === id) {
+      return get(formData, stylePath) as T;
+    }
+  }
+}

package/src/shared/bricks/props/image.ts

@@ -0,0 +1,90 @@
+import { type SchemaOptions, Type, type Static } from "@sinclair/typebox";
+import { prop } from "./helpers";
+import { typedRef } from "~/shared/utils/typed-ref";
+// import { canvasDataURI } from "~/shared/utils/canvas-data-uri";
+
+type PropImageOptions = {
+  defaultImageUrl?: string;
+  showImgSearch?: boolean;
+  noObjectOptions?: boolean;
+};
+
+export function image(title = "Image", options: PropImageOptions = {}) {
+  const { defaultImageUrl, showImgSearch = false } = options;
+  const schema = Type.Object(
+    {
+      src: Type.String({
+        default: defaultImageUrl,
+        title,
+        description: "Image URL. Can be a link to an image or a data URI",
+      }),
+      alt: Type.Optional(
+        Type.String({
+          title: "Alternate Text",
+          description: "Alternative text for the image. Recommended for screen readers and SEO",
+          "ui:placeholder": "Your image description",
+        }),
+      ),
+      fit: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("object-none", { title: "None" }),
+            Type.Literal("object-contain", { title: "Contain" }),
+            Type.Literal("object-cover", { title: "Cover" }),
+            Type.Literal("object-fill", { title: "Fill" }),
+            Type.Literal("object-scale-down", { title: "Scale down" }),
+          ],
+          {
+            title: "Fit",
+            description: "How the image should be resized to fit its container",
+            "ui:field": "enum",
+            "ui:styleId": "#styles:objectFit",
+          },
+        ),
+      ),
+      position: Type.Optional(
+        Type.Union(
+          [
+            Type.Literal("object-top", { title: "Top" }),
+            Type.Literal("object-center", { title: "Center" }),
+            Type.Literal("object-bottom", { title: "Bottom" }),
+            Type.Literal("object-left", { title: "Left" }),
+            Type.Literal("object-right", { title: "Right" }),
+            Type.Literal("object-left-top", { title: "Top left" }),
+            Type.Literal("object-right-top", { title: "Top right" }),
+            Type.Literal("object-left-bottom", { title: "Bottom left" }),
+            Type.Literal("object-right-bottom", { title: "Bottom right" }),
+          ],
+          {
+            "ui:styleId": "#styles:objectPosition",
+            title: "Position",
+            description: "The position of the image inside its container",
+            "ui:field": "enum",
+          },
+        ),
+      ),
+    },
+    {
+      $id: "assets:image",
+      "ui:field": "image",
+      "ui:accept": "image/*",
+      "ui:show-img-search": !!showImgSearch,
+      "ui:no-object-options": !!options.noObjectOptions,
+      default: {
+        alt: "Image",
+        fit: "object-cover",
+        position: "object-center",
+      },
+    },
+  );
+  return prop({
+    title,
+    schema,
+  });
+}
+
+export function imageRef(options: PropImageOptions & SchemaOptions = {}) {
+  return typedRef("assets:image", { ...options, styleId: "#assets:image" });
+}
+
+export type ImageProps = Static<ReturnType<typeof image>>;

package/src/shared/bricks/props/number.ts

@@ -0,0 +1,16 @@
+import { Type, type NumberOptions } from "@sinclair/typebox";
+import { prop } from "./helpers";
+import type { FieldMetadata } from "./types";
+
+type NumberFieldOptions = NumberOptions & FieldMetadata;
+
+export function number(
+  title: string,
+  defaultValue?: number,
+  options: Omit<NumberFieldOptions, "default"> = {},
+) {
+  return prop({
+    title,
+    schema: Type.Number({ default: defaultValue, ...options }),
+  });
+}

package/src/shared/bricks/props/padding.ts

@@ -0,0 +1,21 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { prop } from "./helpers";
+import { typedRef } from "~/shared/utils/typed-ref";
+
+export function padding() {
+  return prop({
+    title: "Padding",
+    schema: Type.String({
+      $id: "styles:padding",
+      description: "Space between the content and the border",
+      "ai:instructions": "Can be a tailwind class like `p-4` or a custom value like `p-[16px]`.",
+      "ui:field": "enum",
+      "ui:responsive": true,
+      "ui:styleId": "#styles:padding",
+    }),
+  });
+}
+
+export const paddingRef = typedRef("styles:padding");
+
+export type PaddingSettings = Static<ReturnType<typeof padding>>;

package/src/shared/bricks/props/position.ts

@@ -0,0 +1,27 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { prop } from "./helpers";
+
+export function position(defaultValue = "flowing", title = "Position") {
+  return prop({
+    title,
+    schema: Type.Union(
+      [
+        Type.Literal("flowing", { title: "Flowing" }),
+        Type.Literal("fixed", { title: "Fixed" }),
+        Type.Literal("sticky", { title: "Sticky" }),
+      ],
+      { default: defaultValue, "ui:styleId": "#styles:position" },
+    ),
+  });
+}
+
+export type PositionSettings = Static<ReturnType<typeof position>>;
+
+export function fixedPositioned(defaultValue = false, title = "Fixed position") {
+  return prop({
+    title,
+    schema: Type.Boolean({ default: defaultValue, "ui:styleId": "#styles:fixedPositioned" }),
+  });
+}
+
+export type FixedPositionedSettings = Static<ReturnType<typeof fixedPositioned>>;

package/src/shared/bricks/props/preset.ts

@@ -0,0 +1,136 @@
+import { Type, type Static } from "@sinclair/typebox";
+import { typedRef } from "~/shared/utils/typed-ref";
+
+export function preset(defaultValue?: string) {
+  return Type.Union(
+    [
+      Type.Literal("surface-1", {
+        title: "Surface 1",
+        description: "Surface elevation 1, light background with dark text.",
+      }),
+      Type.Literal("surface-2", {
+        title: "Surface 2",
+        description: "Surface elevation 2, slightly darker background with dark text.",
+      }),
+      Type.Literal("surface-3", {
+        title: "Surface 3",
+        description: "Surface elevation 3, even darker background with dark text.",
+      }),
+      Type.Literal("prominent-primary", {
+        title: "Prominent Primary",
+        description: "Prominent display on primary-700 background.",
+      }),
+      Type.Literal("prominent-secondary", {
+        title: "Prominent Secondary",
+        description: "Prominent display on secondary-700 background.",
+      }),
+      Type.Literal("prominent-accent", {
+        title: "Prominent Accent",
+        description: "Prominent display on accent-700 background.",
+      }),
+      Type.Literal("medium-primary", {
+        title: "Medium Primary",
+        description: "Filled display on primary-200 background.",
+      }),
+      Type.Literal("medium-secondary", {
+        title: "Medium Secondary",
+        description: "Medium display on secondary-200 background.",
+      }),
+      Type.Literal("medium-accent", {
+        title: "Medium Accent",
+        description: "Medium display on accent-200 background.",
+      }),
+      Type.Literal("subtle-primary", {
+        title: "Subtle Primary",
+        description: "Subtle display on primary-100 background and 1px border.",
+      }),
+      Type.Literal("subtle-secondary", {
+        title: "Subtle Secondary",
+        description: "Subtle display on secondary-100 background and 1px border.",
+      }),
+      Type.Literal("subtle-accent", {
+        title: "Subtle Accent",
+        description: "Subtle display on accent-100 background and 1px border.",
+      }),
+      Type.Literal("preset-none", {
+        title: "None",
+        description:
+          "No background and no border. Useful for bricks inside a card or a container that already have a surface/background.",
+      }),
+    ],
+    {
+      $id: "styles:preset",
+      title: "Preset",
+      description: "Styles presets are used to maintain styles consistency across the application.",
+      default: defaultValue ?? "preset-none",
+    },
+  );
+}
+
+export type Preset = Static<ReturnType<typeof preset>>;
+
+export const presetRef = typedRef("styles:preset");
+
+export const presetsStyleProps = {
+  "surface-1": {
+    "#styles:backgroundColor": "bg-base-100",
+    "#styles:color": "text-base-100",
+    "#styles:border": { color: "border-base-100" },
+  },
+  "surface-2": {
+    "#styles:backgroundColor": "bg-base-200",
+    "#styles:color": "text-base-200",
+    "#styles:border": { color: "border-base-200" },
+  },
+  "surface-3": {
+    "#styles:backgroundColor": "bg-base-300",
+    "#styles:color": "text-base-300",
+    "#styles:border": { color: "border-base-300" },
+  },
+  "prominent-primary": {
+    "#styles:backgroundColor": "bg-primary-700",
+    "#styles:color": "text-primary",
+    "#styles:border": { color: "border-primary-800" },
+  },
+  "prominent-secondary": {
+    "#styles:backgroundColor": "bg-secondary-700",
+    "#styles:color": "text-secondary",
+    "#styles:border": { color: "border-secondary-800" },
+  },
+  "prominent-accent": {
+    "#styles:backgroundColor": "bg-accent-700",
+    "#styles:color": "text-accent",
+    "#styles:border": { color: "border-accent-800" },
+  },
+  "medium-primary": {
+    "#styles:backgroundColor": "bg-primary-200",
+    "#styles:color": "text-primary-800",
+    "#styles:border": { color: "border-primary-300" },
+  },
+  "medium-secondary": {
+    "#styles:backgroundColor": "bg-secondary-200",
+    "#styles:color": "text-secondary-800",
+    "#styles:border": { color: "border-secondary-300" },
+  },
+  "medium-accent": {
+    "#styles:backgroundColor": "bg-accent-200",
+    "#styles:color": "text-accent-800",
+    "#styles:border": { color: "border-accent-300" },
+  },
+  "subtle-primary": {
+    "#styles:backgroundColor": "bg-primary-100",
+    "#styles:color": "text-primary-800",
+    "#styles:border": { color: "border-primary-100" },
+  },
+  "subtle-secondary": {
+    "#styles:backgroundColor": "bg-secondary-100",
+    "#styles:color": "text-secondary-800",
+    "#styles:border": { color: "border-secondary-100" },
+  },
+  "subtle-accent": {
+    "#styles:backgroundColor": "bg-accent-100",
+    "#styles:color": "text-accent-800",
+    "#styles:border": { color: "border-accent-100" },
+  },
+  "preset-none": {},
+};

package/src/shared/bricks/props/string.ts

@@ -0,0 +1,60 @@
+import { type Static, Type, type StringOptions } from "@sinclair/typebox";
+import { prop } from "./helpers";
+import type { jsonStringsSupportedFormats } from "../../ajv";
+import type { FieldMetadata } from "./types";
+import { typedRef } from "~/shared/utils/typed-ref";
+
+type StrFieldOptions = StringOptions &
+  FieldMetadata & {
+    format?: (typeof jsonStringsSupportedFormats)[number];
+  };
+
+export function string(title: string, defaultValue?: string, options: Omit<StrFieldOptions, "default"> = {}) {
+  return prop({
+    title,
+    schema: Type.String({ default: defaultValue, ...options }),
+  });
+}
+
+export function url(title = "URL", defaultValue?: string) {
+  return prop({
+    title,
+    schema: Type.String({
+      format: "uri",
+      "ui:field": "url",
+      default: defaultValue,
+    }),
+  });
+}
+
+const pageIdSchema = Type.String({
+  "ui:field": "page-id",
+});
+
+export function urlOrPageId(title = "URL or Page ID", defaultValue?: string) {
+  return prop({
+    title,
+    schema: Type.Union(
+      [
+        Type.String({
+          format: "uri",
+        }),
+        pageIdSchema,
+      ],
+      {
+        $id: "content:urlOrPageId",
+        default: defaultValue,
+        title: "URL or Page ID",
+        "ui:field": "url-page-id",
+        "ai:instructions":
+          "This field can be a URL or a page ID. Use the page ID when linking to a internal page, and a URL for external links.",
+      },
+    ),
+  });
+}
+
+export type UrlOrPageIdSettings = Static<ReturnType<typeof urlOrPageId>>;
+
+export function urlOrPageIdRef(options: { title?: string; default?: string } = {}) {
+  return typedRef("content:urlOrPageId", { ...options });
+}

package/src/shared/bricks/props/tests/align.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { basicAlign } from "../align";
+
+describe("Align prop test suite", () => {
+  describe("basicAlign", () => {
+    it("should have the correct title with default options", () => {
+      expect(basicAlign().title).toBe("Align");
+    });
+
+    it("should have the correct title with custom options", () => {
+      expect(basicAlign({ title: "Custom Align" }).title).toBe("Custom Align");
+    });
+
+    it("should have correct UI metadata", () => {
+      const schema = basicAlign();
+      expect(schema["ui:field"]).toBe("align-basic");
+      expect(schema["ui:responsive"]).toBe(true);
+    });
+
+    it("should have correct default values", () => {
+      const schema = basicAlign();
+      expect(schema.default).toEqual({
+        horizontal: "justify-start",
+        vertical: "items-center",
+      });
+    });
+
+    it("should accept custom default values", () => {
+      const customDefault = {
+        horizontal: "justify-center",
+        vertical: "items-start",
+      };
+      const schema = basicAlign({ defaultValue: customDefault });
+      expect(schema.default).toEqual(customDefault);
+    });
+  });
+});

package/src/shared/bricks/props/tests/background.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from "vitest";
+import { background, backgroundRef, backgroundColor } from "../background";
+
+describe("Background prop test suite", () => {
+  describe("background", () => {
+    it("should have the correct title", () => {
+      expect(background().title).toBe("Background");
+    });
+
+    it("should have correct schema structure", () => {
+      const schema = background();
+      expect(schema.type).toBe("object");
+      expect(schema).toHaveProperty("properties.color");
+      expect(schema).toHaveProperty("properties.image");
+      expect(schema).toHaveProperty("properties.size");
+      expect(schema).toHaveProperty("properties.repeat");
+    });
+
+    it("should have correct UI metadata", () => {
+      const schema = background();
+      expect(schema["ui:field"]).toBe("background");
+      expect(schema["ui:group"]).toBe("background");
+      expect(schema["ui:group:title"]).toBe("Background");
+    });
+
+    it("should accept custom default values", () => {
+      const customBg = background({
+        defaultValue: {
+          color: "#000000",
+          size: "cover",
+          repeat: "repeat",
+        },
+      });
+      expect(customBg.default).toEqual({
+        color: "#000000",
+        size: "cover",
+        repeat: "repeat",
+      });
+    });
+
+    it("should accept custom title", () => {
+      const customBg = background({ title: "Custom Title" });
+      expect(customBg.title).toBe("Custom Title");
+    });
+
+    describe("color property", () => {
+      it("should have correct metadata", () => {
+        const colorProp = background().properties.color;
+        expect(colorProp.title).toBe("Color");
+        expect(colorProp.type).toBe("string");
+      });
+    });
+
+    describe("image property", () => {
+      it("should have correct metadata", () => {
+        const imageProp = background().properties.image;
+        expect(imageProp.title).toBe("Image");
+        expect(imageProp.type).toBe("string");
+      });
+    });
+
+    describe("size property", () => {
+      it("should have correct metadata", () => {
+        const sizeProp = background().properties.size;
+        expect(sizeProp.default).toBe("auto");
+      });
+    });
+
+    describe("repeat property", () => {
+      it("should have correct metadata", () => {
+        const repeatProp = background().properties.repeat;
+        expect(repeatProp.default).toBe("no-repeat");
+      });
+    });
+  });
+
+  describe("backgroundColor", () => {
+    it("should have the correct title", () => {
+      expect(backgroundColor().title).toBe("Background color");
+    });
+
+    it("should accept custom title", () => {
+      expect(backgroundColor("red", "Custom Title").title).toBe("Custom Title");
+    });
+
+    it("should have correct schema structure", () => {
+      const schema = backgroundColor();
+      expect(schema.type).toBe("string");
+    });
+
+    it("should have correct UI metadata", () => {
+      const schema = backgroundColor();
+      expect(schema["ui:field"]).toBe("color");
+      expect(schema["ui:color-type"]).toBe("background");
+    });
+
+    it("should have correct default value", () => {
+      expect(backgroundColor().default).toBeUndefined();
+      expect(backgroundColor("red").default).toBe("red");
+    });
+  });
+});

package/src/shared/bricks/props/tests/border.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from "vitest";
+import { border } from "../border";
+
+describe("Border prop test suite", () => {
+  const borderSchema = border();
+
+  describe("propBorder", () => {
+    it("should have the correct title", () => {
+      expect(border().title).toBe("Border");
+    });
+  });
+
+  describe("border schema", () => {
+    describe("border.style", () => {
+      it("should have correct metadata", () => {
+        const styleProp = borderSchema.properties.style;
+        expect(styleProp.description).toBe("The brick border style");
+        expect(styleProp["ui:field"]).toBe("enum");
+        expect(styleProp["ui:display"]).toBe("button-group");
+      });
+    });
+
+    describe("border.color", () => {
+      it("should have correct metadata", () => {
+        const colorProp = borderSchema.properties.color;
+        expect(colorProp["ui:field"]).toBe("color");
+        expect(colorProp["ui:color-type"]).toBe("border");
+      });
+    });
+
+    describe("border.width", () => {
+      it("should have correct metadata", () => {
+        const widthProp = borderSchema.properties.width;
+        expect(widthProp["ui:field"]).toBe("enum");
+      });
+    });
+  });
+});

package/src/shared/bricks/props/tests/effects.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from "vitest";
+import { opacity, shadow, textShadow } from "../effects";
+
+describe("Effects props test suite", () => {
+  describe("opacity", () => {
+    it("should have correct title and default value", () => {
+      const prop = opacity();
+      expect(prop.title).toBe("Opacity");
+      expect(prop.default).toBe(1);
+    });
+
+    it("should allow for custom default value", () => {
+      const prop = opacity({ defaultValue: 0.5 });
+      expect(prop.default).toBe(0.5);
+    });
+
+    it("should have correct UI metadata", () => {
+      const prop = opacity();
+      expect(prop["ui:field"]).toBe("slider");
+      expect(prop.minimum).toBe(0.1);
+      expect(prop.maximum).toBe(1);
+      expect(prop.multipleOf).toBe(0.1);
+    });
+  });
+
+  describe("textShadow", () => {
+    it("should have correct title", () => {
+      const prop = textShadow();
+      expect(prop.title).toBe("Text shadow");
+    });
+
+    it("should have correct UI metadata", () => {
+      const schema = textShadow();
+      expect(schema["ui:field"]).toBe("enum");
+    });
+  });
+});