npm package: @qitplus/guijson
Description: A package for using the guijson format
Author: Dane Madsen
Latest version: 1.0.0

# 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

```bash
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

```ts
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:

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

That means event handlers can stay fully serializable:

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

## References Example

Use references if you want reusable or normalized component definitions.

```ts
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