@upstart.gg/sdk 0.0.130 → 0.0.132

package/src/shared/tests/attributes.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from "vitest";
+import {
+  type PageAttributes,
+  resolvePageAttributes,
+  resolveSiteAttributes,
+  type SiteAttributes,
+} from "../attributes";
+
+describe("Attributes test suite", () => {
+  describe("resolvePageAttributes", () => {
+    it("should resolve attributes with default values", () => {
+      const attributes = {};
+      expect(resolvePageAttributes(attributes)).toMatchObject<PageAttributes>({
+        robotsIndexing: true,
+        path: "/",
+        title: "Untitled",
+        description: "",
+        keywords: "",
+      });
+    });
+  });
+  describe("resolveSiteAttributes", () => {
+    it("should resolve site attributes with default values", () => {
+      const attributes = {};
+      expect(resolveSiteAttributes(attributes)).toMatchObject<SiteAttributes>({
+        language: "en",
+        navbar: {},
+      });
+    });
+  });
+});

package/src/shared/theme.ts

@@ -0,0 +1,244 @@
+import { Type, type Static } from "@sinclair/typebox";
+import chroma from "chroma-js";
+import { colorPalette } from "@upstart.gg/style-system/colors";
+import { StringEnum } from "./utils/string-enum";
+import { toLLMSchema } from "./utils/llm";
+
+export const fontStacks = [
+  { value: "system-ui", label: "System UI" },
+  { value: "transitional", label: "Transitional" },
+  { value: "old-style", label: "Old style" },
+  { value: "humanist", label: "Humanist" },
+  { value: "geometric-humanist", label: "Geometric humanist" },
+  { value: "classical-humanist", label: "Classical humanist" },
+  { value: "neo-grotesque", label: "Neo-grotesque" },
+  { value: "monospace-slab-serif", label: "Monospace slab serif" },
+  { value: "monospace-code", label: "Monospace code" },
+  { value: "industrial", label: "Industrial" },
+  { value: "rounded-sans", label: "Rounded sans" },
+  { value: "slab-serif", label: "Slab serif" },
+  { value: "antique", label: "Antique" },
+  { value: "didone", label: "Didone" },
+  { value: "handwritten", label: "Handwritten" },
+];
+
+const headingFont = Type.Object(
+  {
+    type: StringEnum(["stack", "theme", "google"], {
+      title: "Type of font",
+      description: "The type of font. Can be a font stack, a theme font or a Google font",
+    }),
+    family: Type.String({
+      title: "Family",
+      description: "The font family (eg. the name of the font)",
+    }),
+  },
+  {
+    title: "Headings font",
+    description: "Used for titles and headings",
+    additionalProperties: false,
+  },
+);
+
+const bodyFont = Type.Object(
+  {
+    type: StringEnum(["stack", "theme", "google"], {
+      title: "Type of font",
+      description: "The type of font. Can be a font stack, a theme font or a Google font",
+    }),
+    family: Type.String({
+      title: "Family",
+      description: "The font family (eg. the name of the font)",
+    }),
+  },
+  {
+    title: "Body font",
+    description: "Used for paragraphs and body text",
+    additionalProperties: false,
+  },
+);
+
+export const themeSchema = Type.Object(
+  {
+    id: Type.String({ title: "ID", description: "The unique identifier of the theme" }),
+    name: Type.String({ title: "Name", description: "The name of the theme" }),
+    description: Type.String({ title: "Description", description: "The description of the theme" }),
+    tags: Type.Array(Type.String({ title: "Tag" }), { title: "Tags", description: "The tags of the theme" }),
+    browserColorScheme: StringEnum(["light", "dark"], {
+      title: "Browser scheme",
+      description: "Color of browser-provided UI. Either 'light' or 'dark'",
+    }),
+    // Define the theme colors
+    colors: Type.Object(
+      {
+        primary: Type.String({
+          title: "Primary",
+          description: "The brand's primary color.",
+          "ai:instructions": "Use oklch() css notation.",
+          examples: ["oklch(0.62 0.241 354.308)"],
+        }),
+        secondary: Type.String({
+          title: "Secondary",
+          description: "The brand's second most used color",
+          "ai:instructions": "Use oklch() css notation.",
+          examples: ["oklch(0.65 0.22 185)"],
+        }),
+        accent: Type.String({
+          title: "Accent",
+          description: "The brand's least used color",
+          "ai:instructions": "Use oklch() css notation.",
+          examples: ["oklch(0.82 0.18 85)"],
+        }),
+        neutral: Type.String({
+          title: "Neutral",
+          description: "The base neutral color",
+          "ai:instructions": "Use oklch() css notation.",
+          examples: ["oklch(0.38 0.08 280)"],
+        }),
+        base100: Type.String({
+          title: "Base",
+          description:
+            "Base surface color of page, used for blank backgrounds. Should be white or near-white for light color-schemes, and black or near-black for dark color-schemes.",
+          "ai:instructions": "Use oklab() css notation.",
+          examples: ["oklch(0.99 0.008 92)"],
+        }),
+        base200: Type.String({
+          title: "Base 2",
+          description:
+            "Should be darker than base 100 but still light for light color-schemes, and lighter but still dark for dark color-schemes.",
+          "ai:instructions": "Use oklab() css notation.",
+          examples: ["oklch(0.97 0.01 85)"],
+        }),
+        base300: Type.String({
+          title: "Base 3",
+          description:
+            "3rd base color, should be darker than base 200 for light color-schemes, and lighter than base 200 for dark color-schemes.",
+          "ai:instructions": "Use oklab() css notation.",
+          examples: ["oklch(0.95 0.02 80)"],
+        }),
+      },
+      {
+        title: "Theme base colors",
+        description: "The base colors of the theme. Each theme must declare all these colors",
+        additionalProperties: false,
+      },
+    ),
+
+    // Define the theme typography
+    typography: Type.Object(
+      {
+        base: Type.Number({
+          title: "Base font size",
+          description: "The base font size in pixels. It is safe to keep it as is.",
+          "ai:instructions": "A safe value is 16.",
+        }),
+        heading: headingFont,
+        body: bodyFont,
+        alternatives: Type.Array(
+          Type.Object(
+            {
+              body: bodyFont,
+              heading: headingFont,
+            },
+            { additionalProperties: false },
+          ),
+          {
+            title: "Alternative fonts",
+            description: "Alternative fonts that can be suggested to the user. Takes the same shape",
+          },
+        ),
+      },
+      { additionalProperties: false },
+    ),
+  },
+  {
+    additionalProperties: false,
+  },
+);
+
+export type Theme = Static<typeof themeSchema>;
+export const themesArray = Type.Array(themeSchema);
+
+export function getThemesArrayForLLM() {
+  return toLLMSchema(themesArray);
+}
+
+export type ThemesArray = Static<typeof themesArray>;
+export type FontType = Theme["typography"]["body"];
+
+export const defaultTheme: Theme = {
+  id: "_default_",
+  name: "default",
+  description: "Default Upstart theme",
+  tags: ["gradient", "vibrant", "modern", "creative", "dynamic", "artistic", "bold"],
+  browserColorScheme: "light",
+  colors: {
+    base100: "#FFF", // Warm white background
+    base200: "oklch(0.99 0.008 92)", // Soft cream
+    base300: "oklch(0.97 0.01 85)", // Light warm gray
+    primary: "oklch(0.55 0.241 354.308)",
+    secondary: "oklch(0.65 0.22 185)",
+    accent: "oklch(0.82 0.18 85)",
+    neutral: "oklch(0.38 0.08 280)",
+  },
+  typography: {
+    base: 16,
+    heading: { type: "stack", family: "system-ui" },
+    body: { type: "stack", family: "system-ui" },
+    alternatives: [],
+  },
+};
+
+export function isDefaultTheme(theme: Theme): boolean {
+  return theme.id === defaultTheme.id;
+}
+
+/**
+ * Process a theme, eventually fixing colors and translating them to oklch notations
+ * @param theme
+ */
+export function processTheme(theme: Theme): Theme {
+  return {
+    ...theme,
+    typography: {
+      ...theme.typography,
+      base: 16, // override any base size
+    },
+    colors: Object.entries(theme.colors).reduce(
+      (acc, [key, value]) => {
+        const fixedColor = fixOklchColor(value);
+        return {
+          // biome-ignore lint/performance/noAccumulatingSpread: <explanation>
+          ...acc,
+          [key]: fixedColor,
+        };
+      },
+      {} as typeof theme.colors,
+    ),
+  };
+}
+
+function fixOklchColor(color: string) {
+  const valid = chroma.valid(color);
+  if (valid) {
+    return color;
+  }
+  // Try to fix the color if it looks like oklch
+  const oklchRegex = /ok(lch|lab)\(([^)]+)\)/;
+  if (oklchRegex.test(color)) {
+    const withoutComma = color.replace(/,/g, " ");
+    if (chroma.valid(withoutComma)) {
+      return withoutComma;
+    }
+  }
+  // tailwind colors
+  if (/^([a-z]+)-([0-9]+)$/.test(color)) {
+    const [name, shade] = color.split("-");
+    // @ts-ignore
+    const twColor = colorPalette[name]?.[shade] as string | undefined;
+    if (twColor) {
+      return twColor;
+    }
+  }
+  return color;
+}

package/src/shared/themes/README.md

@@ -0,0 +1,34 @@
+# Theme guidelines
+
+## Primary color
+
+Main brand color, used for key actions and important UI elements.
+
+### Uses
+- Primary buttons (600bg)
+- Selected state (100bg, 700 text)
+
+### Shades
+
+- 50-100: Selected states, hover backgrounds
+- 200-300: Subtle highlights
+- 500-600: Buttons, key actions
+- 700: Text links, icons
+- 800-900: Heavy emphasis
+
+## Secondary color
+
+Supporting colors, used for secondary actions and UI elements.
+
+### Shades
+
+- 50-100: Backgrounds, containers
+- 200-300: Borders, dividers
+- 500-600: Secondary buttons
+- 700: Secondary text
+- 800: Headers in secondary contexts
+
+## Accent Color
+
+Used sparingly for attention-grabbing elements and highlights
+

package/src/shared/themes/color-system.ts

@@ -0,0 +1,146 @@
+import chroma from "chroma-js";
+import type { Theme } from "../theme";
+export { default as chroma } from "chroma-js";
+import { kebabCase } from "lodash-es";
+import { css } from "@upstart.gg/style-system/twind";
+
+export type ColorType = keyof Theme["colors"];
+export type ElementColorType = "page-background" | "background" | "text" | "border" | "shadow";
+
+export const baseColors: Record<ColorType, string> = {
+  primary: "Primary color",
+  secondary: "Secondary color",
+  accent: "Accent color",
+  neutral: "Neutral color",
+  base100: "Base color",
+  base200: "Base (level 2)",
+  base300: "Base (level 3)",
+};
+
+export const shadeNumbers = [900, 800, 700, 600, 500, 400, 300, 200, 100, 50] as const;
+type ShadeNumber = (typeof shadeNumbers)[number];
+
+const semanticAliases: Partial<Record<ShadeNumber, string>> = {
+  100: "subtle",
+  300: "light",
+  700: "dark",
+};
+
+export type ElementColor = string;
+
+export function getColorsSuggestions(baseHueOrColor: number | string, theme: Theme) {
+  return [];
+}
+
+export function isStandardColor(color: unknown): boolean {
+  if (typeof color !== "string") {
+    return false;
+  }
+  return (
+    color.startsWith("oklch") ||
+    color.startsWith("oklab") ||
+    color.startsWith("rgb") ||
+    color.startsWith("hsl") ||
+    color.startsWith("#") ||
+    color.startsWith("var(--")
+  );
+}
+
+export function propToStyle(prop: string | number | undefined, cssAttr: string) {
+  if (typeof prop === "undefined") {
+    return undefined;
+  }
+  // @ts-ignore
+  return isStandardColor(prop) || typeof prop === "number" ? css({ [cssAttr as string]: prop }) : prop;
+}
+
+export function getContrastingTextColor(
+  backgroundColor: string | chroma.Color,
+  contrastThreshold = 3.5,
+): string {
+  // Convert the background color to a chroma color object
+  const bgColor = chroma(backgroundColor);
+
+  // Get potential text colors
+  const white = "#ffffff";
+  const black = "#000000";
+
+  // Calculate contrast ratios
+  const contrastWithWhite = chroma.contrast(bgColor, white);
+  const contrastWithBlack = chroma.contrast(bgColor, black);
+
+  // If both options meet the contrast threshold, return the one with better contrast
+  if (contrastWithWhite >= contrastThreshold && contrastWithBlack >= contrastThreshold) {
+    return white;
+    // return contrastWithWhite >= contrastWithBlack ? white : black;
+  }
+
+  // If only one meets the threshold, use that one
+  if (contrastWithWhite >= contrastThreshold) {
+    return white;
+  }
+
+  if (contrastWithBlack >= contrastThreshold) {
+    return black;
+  }
+
+  // If neither meets the threshold, return the one with better contrast
+  // (though it may not meet accessibility standards)
+  return contrastWithWhite >= contrastWithBlack ? white : black;
+}
+export function propToClass(value: string | number | undefined, classPrefix: string) {
+  if (typeof value === "undefined") {
+    return undefined;
+  }
+  return isStandardColor(value) || typeof value === "number" ? `${classPrefix}-[${value}]` : value;
+}
+
+export function generateColorsVars(theme: Theme) {
+  const shades: Record<string, string> = {};
+  const colorNames = Object.keys(baseColors) as ColorType[];
+
+  colorNames.forEach((_colorName) => {
+    const color = theme.colors[_colorName];
+    const colorName = kebabCase(_colorName);
+    // Add the original color as the default (without number suffix)
+    shades[`color-${colorName}`] = color;
+    // Alias it to 500
+    shades[`color-${colorName}-500`] = color;
+
+    // Generate base color content
+    const contentColor = getContrastingTextColor(color);
+    shades[`color-${colorName}-content`] = contentColor;
+    shades[`color-${colorName}-500-content`] = contentColor;
+
+    const baseColor = chroma(color);
+    const darkest = baseColor.darken(2.5);
+    const lightest = baseColor.brighten(3.5);
+
+    const colorScale = chroma.scale([lightest, baseColor, darkest]).domain([50, 500, 900]).mode("oklch");
+
+    // Generate shades for other colors than base colors
+    if (!colorName.startsWith("base")) {
+      shadeNumbers.forEach((shade) => {
+        if (shade === 500) {
+          return;
+        }
+        const varName = `color-${colorName}-${shade}`;
+
+        // Gen color for the specific shade
+        const shadedColor = colorScale(shade);
+        shades[varName] = shadedColor.css("oklch");
+
+        // Gen content color for this same shade
+        const contentColor = getContrastingTextColor(shadedColor);
+        shades[`color-${colorName}-${shade}-content`] = contentColor;
+
+        if (semanticAliases[shade]) {
+          shades[`color-${colorName}-${semanticAliases[shade]}`] = shades[varName];
+          shades[`color-${colorName}-${semanticAliases[shade]}-content`] = contentColor;
+        }
+      });
+    }
+  });
+
+  return shades;
+}

package/src/shared/themes/tests/color-system.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect } from "vitest";
+import { generateColorsVars } from "../color-system";
+import type { Theme } from "~/shared/theme";
+
+const lightTheme: Theme = {
+  id: "light",
+  name: "Light Theme",
+  tags: ["light"],
+  typography: {
+    base: 16,
+    heading: { type: "stack", family: "system-ui" },
+    body: { type: "stack", family: "system-ui" },
+    alternatives: [],
+  },
+  description: "A light theme with oklch colors for better contrast and accessibility.",
+  browserColorScheme: "light",
+  // oklch colors for better contrast and accessibility
+  colors: {
+    primary: "oklch(0.5 0.1 240 / 1)",
+    secondary: "oklch(0.4 0.1 120 / 1)",
+    accent: "oklch(0.3 0.1 60 / 1)",
+    neutral: "oklch(0.6 0.1 0 / 1)",
+    base100: "oklch(0.95 0.1 0 / 1)",
+    base200: "oklch(0.85 0.1 0 / 1)",
+    base300: "oklch(0.75 0.1 0 / 1)",
+  },
+};
+
+const darkTheme: Theme = {
+  id: "dark",
+  name: "Dark Theme",
+  tags: ["dark"],
+  typography: {
+    base: 16,
+    heading: { type: "stack", family: "system-ui" },
+    body: { type: "stack", family: "system-ui" },
+    alternatives: [],
+  },
+  description: "A dark theme with oklch colors for better contrast and accessibility.",
+  browserColorScheme: "dark",
+  // oklch colors for better contrast and accessibility
+  colors: {
+    primary: "oklch(0.2 0.1 240 / 1)",
+    secondary: "oklch(0.3 0.1 120 / 1)",
+    accent: "oklch(0.4 0.1 60 / 1)",
+    neutral: "oklch(0.5 0.1 0 / 1)",
+    base100: "oklch(0.15 0.1 0 / 1)",
+    base200: "oklch(0.25 0.1 0 / 1)",
+    base300: "oklch(0.35 0.1 0 / 1)",
+  },
+};
+
+const redTheme: Theme = {
+  id: "sunset-coral-glow",
+  name: "Sunset Coral Glow",
+  tags: ["warm", "coral", "sunset"],
+  colors: {
+    accent: "oklch(60 0.5 30)",
+    base100: "oklch(99 0.05 0)",
+    base200: "oklch(97 0.1 0)",
+    base300: "oklch(95 0.15 0)",
+    neutral: "oklch(95 0.2 5)",
+    primary: "oklch(85 0.7 20)",
+    secondary: "oklch(75 0.6 25)",
+  },
+  typography: {
+    base: 16,
+    body: {
+      type: "google",
+      family: "Raleway",
+    },
+    heading: {
+      type: "google",
+      family: "Pacifico",
+    },
+    alternatives: [],
+  },
+  browserColorScheme: "light",
+  description: "",
+};
+
+describe("Color system test suite", () => {
+  describe("generateColorsVars", () => {
+    it("Should generate the correct colors for a light theme", () => {
+      const colors = generateColorsVars(lightTheme);
+      expect(colors["color-primary"]).toBe("oklch(0.5 0.1 240 / 1)");
+      expect(colors["color-primary-content"]).toBe("#ffffff"); // White text on primary
+      // Aliases
+      expect(colors["color-primary-subtle"]).toBe(colors["color-primary-100"]);
+      expect(colors["color-primary-light"]).toBe(colors["color-primary-300"]);
+      expect(colors["color-primary-dark"]).toBe(colors["color-primary-700"]);
+
+      // Various colors
+      expect(colors["color-secondary"]).toBe("oklch(0.4 0.1 120 / 1)");
+      expect(colors["color-secondary-content"]).toBe("#ffffff"); // White text on secondary
+      expect(colors["color-accent"]).toBe("oklch(0.3 0.1 60 / 1)");
+      expect(colors["color-accent-content"]).toBe("#ffffff"); // White text on accent
+      expect(colors["color-neutral"]).toBe("oklch(0.6 0.1 0 / 1)");
+      expect(colors["color-neutral-content"]).toBe("#ffffff"); // White text on neutral
+      expect(colors["color-base-100"]).toBe("oklch(0.95 0.1 0 / 1)");
+      expect(colors["color-base-200"]).toBe("oklch(0.85 0.1 0 / 1)");
+      expect(colors["color-base-300"]).toBe("oklch(0.75 0.1 0 / 1)");
+
+      // All shades should be present
+      expect(Object.keys(colors)).toContain("color-primary-50");
+      expect(Object.keys(colors)).toContain("color-primary-100");
+      expect(Object.keys(colors)).toContain("color-primary-200");
+      expect(Object.keys(colors)).toContain("color-primary-300");
+      expect(Object.keys(colors)).toContain("color-primary-400");
+      expect(Object.keys(colors)).toContain("color-primary-500");
+      expect(Object.keys(colors)).toContain("color-primary-600");
+      expect(Object.keys(colors)).toContain("color-primary-700");
+      expect(Object.keys(colors)).toContain("color-primary-800");
+      expect(Object.keys(colors)).toContain("color-primary-900");
+    });
+    it("Should generate the correct colors for a dark theme", () => {
+      const colors = generateColorsVars(darkTheme);
+      expect(colors["color-primary"]).toBe("oklch(0.2 0.1 240 / 1)");
+      expect(colors["color-primary-content"]).toBe("#ffffff"); // White text on primary
+      // Aliases
+      expect(colors["color-primary-subtle"]).toBe(colors["color-primary-100"]);
+      expect(colors["color-primary-light"]).toBe(colors["color-primary-300"]);
+      expect(colors["color-primary-dark"]).toBe(colors["color-primary-700"]);
+
+      // Various colors
+      expect(colors["color-secondary"]).toBe("oklch(0.3 0.1 120 / 1)");
+      expect(colors["color-secondary-content"]).toBe("#ffffff"); // White text on secondary
+      expect(colors["color-accent"]).toBe("oklch(0.4 0.1 60 / 1)");
+      expect(colors["color-accent-content"]).toBe("#ffffff"); // White text on accent
+      expect(colors["color-neutral"]).toBe("oklch(0.5 0.1 0 / 1)");
+      expect(colors["color-neutral-content"]).toBe("#ffffff"); // White text on neutral
+      expect(colors["color-base-100"]).toBe("oklch(0.15 0.1 0 / 1)");
+      expect(colors["color-base-200"]).toBe("oklch(0.25 0.1 0 / 1)");
+      expect(colors["color-base-300"]).toBe("oklch(0.35 0.1 0 / 1)");
+
+      // All shades should be present
+      expect(Object.keys(colors)).toContain("color-primary-50");
+      expect(Object.keys(colors)).toContain("color-primary-100");
+      expect(Object.keys(colors)).toContain("color-primary-200");
+      expect(Object.keys(colors)).toContain("color-primary-300");
+      expect(Object.keys(colors)).toContain("color-primary-400");
+      expect(Object.keys(colors)).toContain("color-primary-500");
+      expect(Object.keys(colors)).toContain("color-primary-600");
+      expect(Object.keys(colors)).toContain("color-primary-700");
+      expect(Object.keys(colors)).toContain("color-primary-800");
+      expect(Object.keys(colors)).toContain("color-primary-900");
+    });
+    it('should not generate "none" oklch values for the dark theme', () => {
+      const colors = generateColorsVars(darkTheme);
+
+      expect(colors["color-primary"], "color primary contains none").not.toContain("none");
+      expect(colors["color-primary-500"], "color-primary-500 contains none").not.toContain("none");
+      expect(colors["color-primary-200"], "color-primary-200 contains none").not.toContain("none");
+      expect(colors["color-primary-content"], "color-primary-content contains none").not.toContain("none");
+      expect(colors["color-secondary"], "color-secondary contains none").not.toContain("none");
+      expect(colors["color-secondary-500"], "color-secondary-500 contains none").not.toContain("none");
+      expect(colors["color-secondary-200"], "color-secondary-200 contains none").not.toContain("none");
+      expect(colors["color-secondary-content"], "color-secondary-content contains none").not.toContain(
+        "none",
+      );
+      expect(colors["color-accent"], "color-accent contains none").not.toContain("none");
+      expect(colors["color-accent-content"], "color-accent-content contains none").not.toContain("none");
+      expect(colors["color-neutral"], "color-neutral contains none").not.toContain("none");
+      expect(colors["color-neutral-content"], "color-neutral-content contains none").not.toContain("none");
+      expect(colors["color-base-100"], "color-base-100 contains none").not.toContain("none");
+      expect(colors["color-base-200"], "color-base-200 contains none").not.toContain("none");
+      expect(colors["color-base-300"], "color-base-300 contains none").not.toContain("none");
+    });
+  });
+});