GuiJson

TypeScript types for a GUI JSON schema inspired by GeoJSON.

guijson provides a typed way to describe UI trees as JSON objects. Like GeoJSON, every object is identified by a type field, which makes the schema easy to serialize, inspect, validate, and render in your own runtime.

Installation

npm install guijson

What It Includes

• A GuiJson union for all supported GUI JSON nodes
• Component types for Container, Image, Text, Button, TextInput, Switch, Column, Row, and Stack
• Reference types for normalized schemas: Reference and ReferenceCollection
• A ComponentCollection type for storing reusable component definitions
• Generic parameters for custom id, style, and properties shapes
• Tuple-based Action types for events such as onPress and onChange

Quick Example

import type { GuiJson } from 'guijson';

type Style = {
  padding?: number;
  gap?: number;
  fontSize?: number;
};

type Props = {
  testId?: string;
};

const screen: GuiJson<string, Style, Props> = {
  type: 'Column',
  id: 'home',
  style: { padding: 24, gap: 12 },
  properties: { testId: 'home-screen' },
  children: [
    {
      type: 'Text',
      text: 'Hello, GuiJson',
      style: { fontSize: 20 },
    },
    {
      type: 'TextInput',
      value: '',
      placeholder: 'Search',
      onChange: ['setSearch'],
    },
    {
      type: 'Button',
      onPress: ['navigate', 'details'],
      child: {
        type: 'Text',
        text: 'Open details',
      },
    },
  ],
};

Core Shape

Every GUI JSON object includes:

• type: the node discriminator
• id?: an optional string or number identifier

Every component may also include:

• class?: a class-like label
• style?: any style shape you define through generics
• properties?: any custom metadata shape you define through generics

Supported Types

Components

• Container
• Image
• Text
• Button
• TextInput
• Switch
• Column
• Row
• Stack

Collections and References

• ComponentCollection
• Reference
• ReferenceCollection

Events

Interactive components use the Action tuple type:

type Action<K extends string = string, A extends Array<any> = Array<any>> =
  [call: K, ...arguments: A];

That means event handlers can stay fully serializable:

const action = ['navigate', 'settings'] as const;

References Example

Use references if you want reusable or normalized component definitions.

import type { ComponentCollection, Reference } from 'guijson';

const components: ComponentCollection = {
  type: 'ComponentCollection',
  components: [
    { id: 'title', type: 'Text', text: 'Dashboard' },
    { id: 'hero', type: 'Image', src: '/hero.png', alt: 'Hero image' },
  ],
};

const titleRef: Reference = {
  type: 'Reference',
  reference: 'title',
};

Notes

• This package currently ships TypeScript declarations only.
• It does not include a renderer, parser, or runtime validator.
• It also exposes a global GuiJSON namespace for non-module usage.

License

MIT