@brika/ui-kit 0.3.0

package/README.md

@@ -0,0 +1,3 @@
+# @brika/ui-kit
+
+Descriptor types and helpers for building Brika plugin UI bricks.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@brika/ui-kit",
+  "version": "0.3.0",
+  "description": "Descriptor types and builder functions for BRIKA plugin UI bricks",
+  "type": "module",
+  "license": "MIT",
+  "author": "BRIKA Team",
+  "homepage": "https://github.com/maxscharwath/brika/tree/main/packages/ui-kit#readme",
+  "bugs": {
+    "url": "https://github.com/maxscharwath/brika/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/maxscharwath/brika.git",
+    "directory": "packages/ui-kit"
+  },
+  "keywords": ["brika", "ui", "bricks", "board", "descriptors"],
+  "exports": {
+    ".": "./src/index.ts",
+    "./jsx-runtime": "./src/jsx-runtime.ts",
+    "./jsx-dev-runtime": "./src/jsx-dev-runtime.ts"
+  },
+  "files": ["src"],
+  "scripts": {
+    "tsc": "bunx --biome tsc --noEmit",
+    "prepublishOnly": "bun run tsc"
+  },
+  "dependencies": {
+    "@brika/shared": "0.3.0",
+    "zod": "^4.3.4"
+  }
+}

package/src/__tests__/define-brick.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Tests for defineBrick
+ */
+
+import { describe, expect, test } from 'bun:test';
+import type {
+  BrickComponent,
+  BrickInstanceContext,
+  BrickTypeSpec,
+  CompiledBrickType,
+} from '../define-brick';
+import { defineBrick } from '../define-brick';
+import { Stat, Text } from '../nodes';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const minimalSpec: BrickTypeSpec = {
+  id: 'test-brick',
+  families: ['sm'],
+};
+
+const fullSpec: BrickTypeSpec = {
+  id: 'thermostat',
+  name: 'Thermostat',
+  description: 'Shows temperature and allows control',
+  icon: 'thermometer',
+  color: '#ff6b35',
+  category: 'climate',
+  families: ['sm', 'md', 'lg'],
+  minSize: { w: 1, h: 1 },
+  maxSize: { w: 6, h: 6 },
+  config: [{ name: 'room', type: 'text', label: 'Room name', default: 'Living Room' }],
+};
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('defineBrick', () => {
+  test('returns a CompiledBrickType with spec and component', () => {
+    const component: BrickComponent = () => Text({ content: 'hello' });
+    const result = defineBrick(minimalSpec, component);
+
+    expect(result).toHaveProperty('spec');
+    expect(result).toHaveProperty('component');
+    expect(result.spec).toBe(minimalSpec);
+    expect(result.component).toBe(component);
+  });
+
+  test('preserves the exact spec reference', () => {
+    const component: BrickComponent = () => [];
+    const result = defineBrick(fullSpec, component);
+    expect(result.spec).toBe(fullSpec);
+  });
+
+  test('preserves the exact component function reference', () => {
+    const component: BrickComponent = () => Text({ content: 'x' });
+    const result = defineBrick(minimalSpec, component);
+    expect(result.component).toBe(component);
+  });
+
+  test('component can return a single ComponentNode', () => {
+    const component: BrickComponent = (ctx) =>
+      Stat({ label: 'Temp', value: ctx.config.temp as number, unit: '°C' });
+    const result = defineBrick(minimalSpec, component);
+
+    const ctx: BrickInstanceContext = {
+      instanceId: 'inst-1',
+      config: { temp: 21.5 },
+    };
+    const output = result.component(ctx);
+    expect(output).toHaveProperty('type', 'stat-value');
+    expect(output).toHaveProperty('value', 21.5);
+  });
+
+  test('component can return an array of ComponentNodes', () => {
+    const component: BrickComponent = () => [
+      Stat({ label: 'A', value: 1 }),
+      Stat({ label: 'B', value: 2 }),
+    ];
+    const result = defineBrick(minimalSpec, component);
+
+    const ctx: BrickInstanceContext = { instanceId: 'inst-2', config: {} };
+    const output = result.component(ctx);
+    expect(Array.isArray(output)).toBe(true);
+    expect((output as unknown[]).length).toBe(2);
+  });
+
+  test('spec with all fields is preserved', () => {
+    const component: BrickComponent = () => [];
+    const result = defineBrick(fullSpec, component);
+
+    expect(result.spec.id).toBe('thermostat');
+    expect(result.spec.name).toBe('Thermostat');
+    expect(result.spec.description).toBe('Shows temperature and allows control');
+    expect(result.spec.icon).toBe('thermometer');
+    expect(result.spec.color).toBe('#ff6b35');
+    expect(result.spec.category).toBe('climate');
+    expect(result.spec.families).toEqual(['sm', 'md', 'lg']);
+    expect(result.spec.minSize).toEqual({ w: 1, h: 1 });
+    expect(result.spec.maxSize).toEqual({ w: 6, h: 6 });
+    expect(result.spec.config).toHaveLength(1);
+  });
+
+  test('component receives instanceId and config', () => {
+    let receivedCtx: BrickInstanceContext | null = null;
+    const component: BrickComponent = (ctx) => {
+      receivedCtx = ctx;
+      return Text({ content: 'test' });
+    };
+
+    const result = defineBrick(minimalSpec, component);
+    const ctx: BrickInstanceContext = {
+      instanceId: 'brick-abc',
+      config: { key1: 'value1', key2: 42 },
+    };
+    result.component(ctx);
+
+    expect(receivedCtx).not.toBeNull();
+    expect(receivedCtx!.instanceId).toBe('brick-abc');
+    expect(receivedCtx!.config).toEqual({ key1: 'value1', key2: 42 });
+  });
+});

package/src/__tests__/mutations.test.ts

@@ -0,0 +1,211 @@
+/**
+ * Tests for applyMutations
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { MUT } from '../descriptors';
+import type { BoxNode, ButtonNode, ColumnNode, ComponentNode, Mutation, TextNode } from '../index';
+import { applyMutations } from '../mutations';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+const text = (content: string): TextNode => ({ type: 'text', content });
+
+const column = (children: ComponentNode[]): ColumnNode => ({ type: 'column', children });
+
+/** Extract children from a container node at a given index in the result array. */
+function childrenAt(nodes: ComponentNode[], index: number): ComponentNode[] {
+  const node = nodes[index];
+  if (node && 'children' in node) return node.children;
+  throw new Error(`Node at index ${index} has no children`);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('applyMutations', () => {
+  describe('create', () => {
+    test('appends node when index >= length', () => {
+      const body = [text('A')];
+      const result = applyMutations(body, [[MUT.CREATE, '1', text('B')]]);
+
+      expect(result).toHaveLength(2);
+      expect(result[1]).toHaveProperty('content', 'B');
+    });
+
+    test('inserts node at index', () => {
+      const body = [text('A'), text('C')];
+      const result = applyMutations(body, [[MUT.CREATE, '1', text('B')]]);
+
+      expect(result).toHaveLength(3);
+      expect(result[0]).toHaveProperty('content', 'A');
+      expect(result[1]).toHaveProperty('content', 'B');
+      expect(result[2]).toHaveProperty('content', 'C');
+    });
+
+    test('inserts at beginning', () => {
+      const body = [text('B')];
+      const result = applyMutations(body, [[MUT.CREATE, '0', text('A')]]);
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toHaveProperty('content', 'A');
+      expect(result[1]).toHaveProperty('content', 'B');
+    });
+  });
+
+  describe('replace', () => {
+    test('replaces node at index in-place', () => {
+      const button: ButtonNode = { type: 'button', label: 'Click' };
+      const body = [text('A'), text('B')];
+      const result = applyMutations(body, [[MUT.REPLACE, '0', button]]);
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toBe(button);
+      expect(result[1]).toHaveProperty('content', 'B');
+    });
+  });
+
+  describe('update', () => {
+    test('merges props into existing node', () => {
+      const body = [text('Hello')];
+      const result = applyMutations(body, [[MUT.UPDATE, '0', { content: 'Updated' }]]);
+
+      expect(result[0]).toHaveProperty('content', 'Updated');
+      expect(result[0]).toHaveProperty('type', 'text');
+    });
+
+    test('adds new props without removing existing ones', () => {
+      const body = [text('Hello')];
+      const result = applyMutations(body, [[MUT.UPDATE, '0', { variant: 'heading' }]]);
+
+      expect(result[0]).toHaveProperty('content', 'Hello');
+      expect(result[0]).toHaveProperty('variant', 'heading');
+    });
+
+    test('removes props listed in removed array', () => {
+      const box: BoxNode = { type: 'box', blur: 'sm', padding: 'lg', children: [] };
+      const result = applyMutations([box], [[MUT.UPDATE, '0', {}, ['blur']]]);
+
+      expect(result[0]).not.toHaveProperty('blur');
+      expect(result[0]).toHaveProperty('padding', 'lg');
+    });
+
+    test('preserves null as a legitimate prop value', () => {
+      const body = [text('Hello')];
+      const result = applyMutations(body, [[MUT.UPDATE, '0', { color: null }]]);
+
+      expect(result[0]).toHaveProperty('color', null);
+    });
+  });
+
+  describe('remove', () => {
+    test('removes node at index', () => {
+      const body = [text('A'), text('B'), text('C')];
+      const result = applyMutations(body, [[MUT.REMOVE, '1']]);
+
+      expect(result).toHaveLength(2);
+      expect(result[0]).toHaveProperty('content', 'A');
+      expect(result[1]).toHaveProperty('content', 'C');
+    });
+
+    test('removes first node', () => {
+      const body = [text('A'), text('B')];
+      const result = applyMutations(body, [[MUT.REMOVE, '0']]);
+
+      expect(result).toHaveLength(1);
+      expect(result[0]).toHaveProperty('content', 'B');
+    });
+  });
+
+  describe('nested paths', () => {
+    test('updates a nested child', () => {
+      const body = [column([text('inner')])];
+      const result = applyMutations(body, [[MUT.UPDATE, '0.0', { content: 'updated-inner' }]]);
+
+      const children = childrenAt(result, 0);
+      expect(children[0]).toHaveProperty('content', 'updated-inner');
+    });
+
+    test('creates a nested child', () => {
+      const body = [column([text('first')])];
+      const result = applyMutations(body, [[MUT.CREATE, '0.1', text('second')]]);
+
+      const children = childrenAt(result, 0);
+      expect(children).toHaveLength(2);
+      expect(children[1]).toHaveProperty('content', 'second');
+    });
+
+    test('removes a nested child', () => {
+      const body = [column([text('A'), text('B')])];
+      const result = applyMutations(body, [[MUT.REMOVE, '0.0']]);
+
+      const children = childrenAt(result, 0);
+      expect(children).toHaveLength(1);
+      expect(children[0]).toHaveProperty('content', 'B');
+    });
+  });
+
+  describe('structural sharing', () => {
+    test('siblings keep original references after update', () => {
+      const a = text('A');
+      const b = text('B');
+      const body = [a, b];
+
+      const result = applyMutations(body, [[MUT.UPDATE, '0', { content: 'A2' }]]);
+
+      // Updated node is a new reference
+      expect(result[0]).not.toBe(a);
+      // Sibling keeps original reference
+      expect(result[1]).toBe(b);
+    });
+
+    test('parent is new reference but sibling subtrees are shared', () => {
+      const child0 = text('unchanged');
+      const child1 = text('will-change');
+      const body = [column([child0, child1])];
+
+      const result = applyMutations(body, [[MUT.UPDATE, '0.1', { content: 'changed' }]]);
+
+      // Parent container is a new reference
+      expect(result[0]).not.toBe(body[0]);
+      // Unchanged sibling keeps reference
+      expect(childrenAt(result, 0)[0]).toBe(child0);
+    });
+  });
+
+  describe('batch mutations', () => {
+    test('applies multiple mutations in sequence', () => {
+      const body = [text('A')];
+      const mutations: Mutation[] = [
+        [MUT.CREATE, '1', text('B')],
+        [MUT.CREATE, '2', text('C')],
+        [MUT.UPDATE, '0', { content: 'A2' }],
+      ];
+
+      const result = applyMutations(body, mutations);
+
+      expect(result).toHaveLength(3);
+      expect(result[0]).toHaveProperty('content', 'A2');
+      expect(result[1]).toHaveProperty('content', 'B');
+      expect(result[2]).toHaveProperty('content', 'C');
+    });
+  });
+
+  describe('edge cases', () => {
+    test('empty mutations returns same array', () => {
+      const body = [text('A')];
+      const result = applyMutations(body, []);
+      expect(result).toBe(body);
+    });
+
+    test('returns nodes unchanged when targeting non-existent nested path on leaf', () => {
+      const body = [text('leaf')];
+      // text node has no children, so path "0.0" should return nodes unchanged
+      const result = applyMutations(body, [[MUT.UPDATE, '0.0', { content: 'nope' }]]);
+      expect(result).toBe(body);
+    });
+  });
+});