dekit-cli 0.4.2 → 0.5.0

package/src/editor-server.ts

@@ -20,10 +20,18 @@ export async function startEditorServer(
       for (const [name, def] of Object.entries(config.pages)) {
         pagePaths[name] = join(config.baseDir, def.template);
       }
+      const pageProperties: Record<string, Record<string, { type: string; default: unknown }>> = {};
+      for (const [name, def] of Object.entries(config.pages)) {
+        if (def.properties) {
+          pageProperties[name] = def.properties;
+        }
+      }
       const payload = {
         pages: Object.keys(config.pages),
         pagePaths,
+        pageProperties,
         components: Object.keys(config.components),
+        device: config.device ?? null,
         designServerUrl: `http://localhost:${designPort}`,
       };
       res.setHeader("Content-Type", "application/json");

package/src/parser.test.ts

@@ -55,6 +55,170 @@ pages:
     ).rejects.toThrow(/not found|does not exist/i);
   });
 
+  test("parses device as preset name string", async () => {
+    const yaml = `
+version: 1.0
+device: "iPhone 16"
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device).toEqual({
+      width: 393,
+      height: 852,
+      dpr: 3,
+      name: "iPhone 16",
+    });
+  });
+
+  test("parses device as custom dimensions object", async () => {
+    const yaml = `
+version: 1.0
+device:
+  width: 400
+  height: 800
+  dpr: 2
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device).toEqual({
+      width: 400,
+      height: 800,
+      dpr: 2,
+    });
+  });
+
+  test("device defaults dpr to 1 when omitted", async () => {
+    const yaml = `
+version: 1.0
+device:
+  width: 400
+  height: 800
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device!.dpr).toBe(1);
+  });
+
+  test("device is undefined when not specified", async () => {
+    const yaml = `
+version: 1.0
+pages: {}
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.device).toBeUndefined();
+  });
+
+  test("rejects unknown device preset name", async () => {
+    const yaml = `
+version: 1.0
+device: "Nokia 3310"
+pages: {}
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/Unknown device/i);
+  });
+
+  test("rejects device object without width/height", async () => {
+    const yaml = `
+version: 1.0
+device:
+  dpr: 2
+pages: {}
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/width.*height/i);
+  });
+
+  test("parses page properties", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      showBanner:
+        type: boolean
+        default: true
+      itemCount:
+        type: number
+        default: 3
+      title:
+        type: string
+        default: "Hello"
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.pages["home"].properties).toEqual({
+      showBanner: { type: "boolean", default: true },
+      itemCount: { type: "number", default: 3 },
+      title: { type: "string", default: "Hello" },
+    });
+  });
+
+  test("page without properties has undefined properties", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+`;
+    const config = await parseDesignConfig("/fake/dekit.yaml", yaml);
+    expect(config.pages["home"].properties).toBeUndefined();
+  });
+
+  test("rejects invalid property type", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      color:
+        type: color
+        default: red
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/Invalid type.*color/i);
+  });
+
+  test("rejects property with mismatched default type", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      count:
+        type: number
+        default: "not a number"
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/must be a number/i);
+  });
+
+  test("rejects property missing default", async () => {
+    const yaml = `
+version: 1.0
+pages:
+  home:
+    template: "pages/home/home.html"
+    style: "pages/home/home.css"
+    properties:
+      flag:
+        type: boolean
+`;
+    await expect(
+      parseDesignConfig("/fake/dekit.yaml", yaml)
+    ).rejects.toThrow(/Missing default/i);
+  });
+
   test("rejects missing version field", async () => {
     const yaml = `
 global-style: "global.css"

package/src/parser.ts

@@ -2,7 +2,8 @@ import { readFile } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import yaml from "js-yaml";
-import type { DesignConfig, ComponentDef, PageDef } from "./types.js";
+import type { DesignConfig, DeviceConfig, ComponentDef, PageDef, PropertyDef, PropertyType } from "./types.js";
+import { DEVICE_PRESETS } from "./devices.js";
 
 export async function parseDesignConfig(
   configPath: string,
@@ -24,6 +25,8 @@ export async function parseDesignConfig(
   // Validate file paths if the base directory actually exists on disk
   const shouldValidateFiles = existsSync(baseDir);
 
+  const device = parseDevice(doc.device);
+
   const globalStyle = (doc["global-style"] as string) ?? "";
   if (globalStyle && shouldValidateFiles) {
     const globalStylePath = join(baseDir, globalStyle);
@@ -51,24 +54,92 @@ export async function parseDesignConfig(
   }
 
   const rawPages =
-    (doc.pages as Record<string, { template: string; style: string }>) ?? {};
+    (doc.pages as Record<string, { template: string; style: string; properties?: Record<string, unknown> }>) ?? {};
   const pages: Record<string, PageDef> = {};
   for (const [key, val] of Object.entries(rawPages)) {
     if (shouldValidateFiles) {
       validateFilePaths(baseDir, key, val.template, val.style);
     }
-    pages[key] = { template: val.template, style: val.style };
+    const properties = val.properties ? parseProperties(key, val.properties) : undefined;
+    pages[key] = { template: val.template, style: val.style, properties };
   }
 
   return {
     version: doc.version as number,
     globalStyle,
+    device,
     components,
     pages,
     baseDir,
   };
 }
 
+function parseDevice(raw: unknown): DeviceConfig | undefined {
+  if (raw == null) return undefined;
+
+  if (typeof raw === "string") {
+    const normalizedInput = raw.toLowerCase().replace(/\s+/g, "-");
+    const preset = DEVICE_PRESETS.find(
+      (d) => d.name.toLowerCase().replace(/\s+/g, "-") === normalizedInput
+    );
+    if (!preset) {
+      throw new Error(
+        `Unknown device: "${raw}". Available: ${DEVICE_PRESETS.map((d) => d.name).join(", ")}`
+      );
+    }
+    return { width: preset.width, height: preset.height, dpr: preset.dpr, name: preset.name };
+  }
+
+  if (typeof raw === "object") {
+    const obj = raw as Record<string, unknown>;
+    const width = obj.width;
+    const height = obj.height;
+    if (typeof width !== "number" || typeof height !== "number") {
+      throw new Error("Device config must have numeric 'width' and 'height'");
+    }
+    const dpr = typeof obj.dpr === "number" ? obj.dpr : 1;
+    return { width, height, dpr };
+  }
+
+  throw new Error("Invalid device config: expected a device name string or {width, height, dpr} object");
+}
+
+const VALID_PROPERTY_TYPES: PropertyType[] = ["boolean", "number", "string"];
+
+function parseProperties(
+  pageKey: string,
+  raw: Record<string, unknown>
+): Record<string, PropertyDef> {
+  const result: Record<string, PropertyDef> = {};
+  for (const [name, def] of Object.entries(raw)) {
+    if (!def || typeof def !== "object") {
+      throw new Error(
+        `Invalid property "${name}" on page "${pageKey}": expected {type, default}`
+      );
+    }
+    const obj = def as Record<string, unknown>;
+    const type = obj.type as string;
+    if (!VALID_PROPERTY_TYPES.includes(type as PropertyType)) {
+      throw new Error(
+        `Invalid type "${type}" for property "${name}" on page "${pageKey}". Must be: ${VALID_PROPERTY_TYPES.join(", ")}`
+      );
+    }
+    if (obj.default == null) {
+      throw new Error(
+        `Missing default for property "${name}" on page "${pageKey}"`
+      );
+    }
+    const expectedType = type === "boolean" ? "boolean" : type === "number" ? "number" : "string";
+    if (typeof obj.default !== expectedType) {
+      throw new Error(
+        `Default value for "${name}" on page "${pageKey}" must be a ${type}`
+      );
+    }
+    result[name] = { type: type as PropertyType, default: obj.default };
+  }
+  return result;
+}
+
 function validateFilePaths(
   baseDir: string,
   key: string,

package/src/types.ts

@@ -3,14 +3,30 @@ export interface ComponentDef {
   style: string;
 }
 
+export type PropertyType = "boolean" | "number" | "string";
+
+export interface PropertyDef {
+  type: PropertyType;
+  default: unknown;
+}
+
 export interface PageDef {
   template: string;
   style: string;
+  properties?: Record<string, PropertyDef>;
+}
+
+export interface DeviceConfig {
+  width: number;
+  height: number;
+  dpr: number;
+  name?: string;
 }
 
 export interface DesignConfig {
   version: number;
   globalStyle: string;
+  device?: DeviceConfig;
   components: Record<string, ComponentDef>;
   pages: Record<string, PageDef>;
   baseDir: string; // absolute path to .dekit/ directory (where dekit.yaml lives)

package/src/vite-plugin-dekit.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { assemblePageHtml } from "./vite-plugin-dekit.js";
+import { assemblePageHtml, resolvePageProps } from "./vite-plugin-dekit.js";
 import type { DesignConfig } from "./types.js";
 import { join } from "node:path";
 
@@ -59,4 +59,88 @@ describe("assemblePageHtml", () => {
     expect(html).toContain("<slot></slot>");
     expect(html).not.toMatch(/innerHTML\s*=\s*`\s*<template>/);
   });
+
+  test("injects __DEKIT_PROPS__ when page has properties", async () => {
+    const configWithProps: DesignConfig = {
+      ...mockConfig,
+      pages: {
+        home: {
+          ...mockConfig.pages["home"],
+          properties: {
+            showBanner: { type: "boolean", default: true },
+            count: { type: "number", default: 3 },
+          },
+        },
+      },
+    };
+    const html = await assemblePageHtml(configWithProps, "home");
+    expect(html).toContain("window.__DEKIT_PROPS__");
+    expect(html).toContain('"showBanner":true');
+    expect(html).toContain('"count":3');
+  });
+
+  test("does not inject __DEKIT_PROPS__ when page has no properties", async () => {
+    const html = await assemblePageHtml(mockConfig, "home");
+    expect(html).not.toContain("__DEKIT_PROPS__");
+  });
+
+  test("props override applies over defaults", async () => {
+    const configWithProps: DesignConfig = {
+      ...mockConfig,
+      pages: {
+        home: {
+          ...mockConfig.pages["home"],
+          properties: {
+            showBanner: { type: "boolean", default: true },
+            count: { type: "number", default: 3 },
+          },
+        },
+      },
+    };
+    const html = await assemblePageHtml(configWithProps, "home", {
+      props: { showBanner: "false", count: "10" },
+    });
+    expect(html).toContain('"showBanner":false');
+    expect(html).toContain('"count":10');
+  });
+});
+
+describe("resolvePageProps", () => {
+  test("returns defaults when no overrides", () => {
+    const result = resolvePageProps({
+      properties: {
+        flag: { type: "boolean", default: true },
+        num: { type: "number", default: 5 },
+        str: { type: "string", default: "hi" },
+      },
+    });
+    expect(result).toEqual({ flag: true, num: 5, str: "hi" });
+  });
+
+  test("overrides convert types based on schema", () => {
+    const result = resolvePageProps(
+      {
+        properties: {
+          flag: { type: "boolean", default: true },
+          num: { type: "number", default: 5 },
+          str: { type: "string", default: "hi" },
+        },
+      },
+      { flag: "false", num: "42", str: "world" }
+    );
+    expect(result).toEqual({ flag: false, num: 42, str: "world" });
+  });
+
+  test("ignores unknown override keys", () => {
+    const result = resolvePageProps(
+      { properties: { flag: { type: "boolean", default: true } } },
+      { flag: "false", unknown: "value" }
+    );
+    expect(result).toEqual({ flag: false });
+  });
+
+  test("returns empty object when no properties defined", () => {
+    expect(resolvePageProps({})).toEqual({});
+    expect(resolvePageProps({ properties: undefined })).toEqual({});
+  });
 });

package/src/vite-plugin-dekit.ts

@@ -5,10 +5,38 @@ import { join } from "node:path";
 import { generateComponentRegistrationScript } from "./injected/register-components.js";
 import { generateInspectorScript } from "./injected/inspector.js";
 
+export function resolvePageProps(
+  pageDef: { properties?: Record<string, { type: string; default: unknown }> },
+  overrides?: Record<string, string>
+): Record<string, unknown> {
+  const props: Record<string, unknown> = {};
+  if (!pageDef.properties) return props;
+
+  for (const [key, def] of Object.entries(pageDef.properties)) {
+    props[key] = def.default;
+  }
+
+  if (overrides) {
+    for (const [key, raw] of Object.entries(overrides)) {
+      const def = pageDef.properties[key];
+      if (!def) continue;
+      if (def.type === "boolean") {
+        props[key] = raw === "true";
+      } else if (def.type === "number") {
+        props[key] = Number(raw);
+      } else {
+        props[key] = raw;
+      }
+    }
+  }
+
+  return props;
+}
+
 export async function assemblePageHtml(
   config: DesignConfig,
   pageName: string,
-  options?: { inspector?: boolean }
+  options?: { inspector?: boolean; props?: Record<string, string> }
 ): Promise<string> {
   const pageDef = config.pages[pageName];
   if (!pageDef) {
@@ -29,6 +57,11 @@ export async function assemblePageHtml(
     ? `<script>\n${generateInspectorScript()}\n</script>`
     : "";
 
+  const resolvedProps = resolvePageProps(pageDef, options?.props);
+  const propsBlock = Object.keys(resolvedProps).length > 0
+    ? `<script>window.__DEKIT_PROPS__ = ${JSON.stringify(resolvedProps)};</script>\n`
+    : "";
+
   return `<!DOCTYPE html>
 <html>
 <head>
@@ -39,7 +72,7 @@ export async function assemblePageHtml(
   <link rel="stylesheet" href="/@design/${pageDef.style}">
 </head>
 <body>
-${pageTemplate}
+${propsBlock}${pageTemplate}
 <script type="module">
 ${componentScript}
 </script>
@@ -85,9 +118,16 @@ export function dekitPlugin(configRef: { current: DesignConfig }): Plugin {
           const pageName = pageMatch[1];
           const urlObj = new URL(url, "http://localhost");
           const noInspector = urlObj.searchParams.has("noinspector");
+          const props: Record<string, string> = {};
+          for (const [key, value] of urlObj.searchParams.entries()) {
+            if (key.startsWith("props.")) {
+              props[key.slice(6)] = value;
+            }
+          }
           try {
             const html = await assemblePageHtml(configRef.current, pageName, {
               inspector: !noInspector,
+              props: Object.keys(props).length > 0 ? props : undefined,
             });
             res.setHeader("Content-Type", "text/html");
             res.end(html);

package/templates/projects/mobile/dekit.yaml

@@ -1,4 +1,5 @@
 version: 1.0
+device: "iPhone 16"
 global-style: "global.css"
 
 components: {}