Skip to content

Commit eb17212

Browse files
GerardPaligotGerardPaligot
committed
docs: create README.md files for shared and ui and update the root one.
Closes #13
1 parent 5c06394 commit eb17212

File tree

4 files changed

+77
-173
lines changed

4 files changed

+77
-173
lines changed

‎README.md‎

Lines changed: 6 additions & 172 deletions
Original file line numberDiff line numberDiff line change
@@ -1,179 +1,13 @@
1-
# jsonforms-kotlin
2-
31
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
42

5-
`jsonforms-kotlin` is a Kotlin Multiplatform implementation of the [JSONForms](https://jsonforms.io/)
6-
standard from the Eclipse Foundation. It leverages the power of [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/)
7-
to render dynamic forms based on JSON Schemas and UI Schemas across various platforms,
8-
including Android, iOS, and the JVM.
9-
10-
**Key aspects:**
11-
12-
* **JSONForms Standard:** Adheres to the JSONForms specification, enabling declarative form definition and rendering.
13-
* **Kotlin Multiplatform:** Built with Kotlin Multiplatform, ensuring code reusability and maintainability across different target platforms.
14-
* **Compose Multiplatform:** Utilizes JetBrains' modern UI framework, Compose Multiplatform, for building native-like user interfaces on Android, iOS, and JVM.
15-
* **Renderers:** Provides built-in renderers for popular design systems, including Material 3 and the Apple ecosystem (via Compose Cupertino).
16-
* **Goal:** The primary goal of this library is to provide a flexible and platform-agnostic way to generate and manage forms within Kotlin Multiplatform applications, simplifying UI development for data entry and configuration.
17-
18-
## Usage
19-
20-
This section demonstrates basic usage of the `jsonforms-kotlin` library with examples showcasing
21-
the Material 3 and Cupertino renderers.
22-
23-
**Common Setup:**
24-
25-
Before using any renderer, you'll typically need to define your JSON Schema and UI Schema:
26-
27-
```kotlin
28-
val schema = Schema(
29-
properties = persistentMapOf(
30-
"email" to StringProperty(
31-
pattern = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}\$"
32-
),
33-
"password" to StringProperty()
34-
),
35-
required = persistentListOf("email", "password")
36-
)
37-
val uiSchema = VerticalLayout(
38-
elements = persistentListOf(
39-
Control(
40-
scope = "#/properties/email",
41-
label = "Email"
42-
),
43-
Control(
44-
scope = "#/properties/password",
45-
label = "Password",
46-
options = ControlOptions(format = Format.Password)
47-
)
48-
)
49-
)
50-
```
51-
52-
**Using Material 3 Renderer**
53-
54-
To use the Material 3 renderer, ensure you have the corresponding dependency in your
55-
`build.gradle.kts` file (this will be detailed in the Download section later).
56-
57-
```kotlin
58-
val state = rememberJsonFormState(initialValues = mutableMapOf())
59-
JsonForm(
60-
schema = schema, // your schema
61-
uiSchema = uiSchema, // your ui schema
62-
state = state,
63-
layoutContent = { Material3Layout(content = it) },
64-
stringContent = { id ->
65-
val value = state[id].value as String?
66-
val error = state.error(id = id).value
67-
Material3StringProperty(
68-
value = value,
69-
error = error?.message,
70-
onValueChange = {
71-
state[id] = it
72-
}
73-
)
74-
},
75-
numberContent = { id ->
76-
val value = state[id].value as String?
77-
val error = state.error(id = id).value
78-
Material3NumberProperty(
79-
value = value,
80-
error = error?.message,
81-
onValueChange = {
82-
state[id] = it
83-
}
84-
)
85-
},
86-
booleanContent = { id ->
87-
val value = state[id].value as Boolean?
88-
Material3BooleanProperty(
89-
value = value,
90-
onValueChange = {
91-
state[id] = it
92-
}
93-
)
94-
}
95-
)
96-
```
97-
98-
![Material 3 Example](./captures/example-material3.png)
99-
100-
**Using Cupertino Renderer**
101-
102-
To use the Cupertino renderer, ensure you have the corresponding dependency in your
103-
`build.gradle.kts` file (this will be detailed in the Download section later).
104-
105-
```kotlin
106-
val state = rememberJsonFormState(initialValues = mutableMapOf())
107-
JsonForm(
108-
schema = schema, // your schema
109-
uiSchema = uiSchema, // your uischema
110-
layoutContent = { CupertinoLayout(content = it) },
111-
stringContent = { id ->
112-
val value = state[id].value as String?
113-
val error = state.error(id = id).value
114-
CupertinoStringProperty(
115-
value = value,
116-
error = error?.message,
117-
onValueChange = {
118-
state[id] = it
119-
}
120-
)
121-
},
122-
numberContent = { id ->
123-
val value = state[id].value as String?
124-
val error = state.error(id = id).value
125-
CupertinoNumberProperty(
126-
value = value,
127-
error = error?.message,
128-
onValueChange = {
129-
state[id] = it
130-
}
131-
)
132-
},
133-
booleanContent = { id ->
134-
val value = state[id].value as Boolean?
135-
CupertinoBooleanProperty(
136-
value = value ?: false,
137-
onValueChange = {
138-
state[id] = it
139-
}
140-
)
141-
}
142-
)
143-
```
144-
145-
![Cupertino Example](./captures/example-cupertino.png)
146-
147-
## Architecture
3+
## jsonforms-kotlin
1484

149-
```mermaid
150-
graph TD
151-
material3 --> ui
152-
cupertino --> ui
153-
ui --> shared
154-
```
155-
156-
This diagram illustrates the modular architecture of `jsonforms-kotlin`:
157-
158-
* The `shared` module contains the core data models for JSON Schema, UI Schema, and the data handled by the forms.
159-
* The `ui` module provides the foundational `JsonForm` composable and defines the Renderer interface. It depends on the `shared` module for the models but remains agnostic of any specific UI design system.
160-
* The `material3` module implements a Renderer specifically for the [Material 3 design system](https://m3.material.io/). It depends on the `ui` module and provides Compose Multiplatform components that adhere to Material 3 guidelines.
161-
* The `cupertino` module implements a Renderer for the Apple ecosystem, leveraging the [compose-cupertino library](https://github.com/schott12521/compose-cupertino). It also depends on the `ui` module and offers Cupertino-style Compose Multiplatform components.
162-
163-
## Download
164-
165-
The `jsonforms-kotlin` library is not yet available on Maven Central in release mode but you can
166-
already use the latest SNAPSHOT version, `1.0.0-SNAPSHOT`.
5+
`jsonforms-kotlin` is a Kotlin Multiplatform implementation of the [JSONForms](https://jsonforms.io/)
6+
standard from the Eclipse Foundation. It leverages the power of [Compose Multiplatform](https://www.jetbrains.com/lp/compose-multiplatform/)
7+
to render dynamic forms based on JSON Schemas and UI Schemas across various platforms,
8+
including Android, iOS, and the JVM.
1679

168-
```kotlin
169-
val version = "1.0.0-SNAPSHOT"
170-
dependencies {
171-
implementation("com.paligot.jsonforms.kotlin:core:$version")
172-
implementation("com.paligot.jsonforms.kotlin:ui:$version")
173-
implementation("com.paligot.jsonforms.kotlin:material3:$version")
174-
implementation("com.paligot.jsonforms.kotlin:cupertino:$version")
175-
}
176-
```
10+
Check out the website for more information: https://gerard.paligot.com/jsonforms-kotlin/
17711

17812
## License
17913

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ already use the latest SNAPSHOT version, `1.0.0-SNAPSHOT`:
2020
```kotlin
2121
val version = "1.0.0-SNAPSHOT"
2222
dependencies {
23-
implementation("com.paligot.jsonforms.kotlin:core:$version")
23+
implementation("com.paligot.jsonforms.kotlin:shared:$version")
2424
implementation("com.paligot.jsonforms.kotlin:ui:$version")
2525
implementation("com.paligot.jsonforms.kotlin:material3:$version")
2626
implementation("com.paligot.jsonforms.kotlin:cupertino:$version")

‎shared/README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Shared
2+
3+
This module contains the core models, schema definitions, and utilities. It is designed to be used
4+
across all platforms and renderer modules, providing the foundation for dynamic form generation and
5+
validation.
6+
7+
## Usage
8+
9+
Add the dependency to your project:
10+
11+
```kotlin
12+
dependencies {
13+
implementation("com.paligot.jsonforms.kotlin:shared:<version>")
14+
}
15+
```
16+
17+
Import and use the schema and UI schema models in your code:
18+
19+
```kotlin
20+
import com.paligot.jsonforms.kotlin.models.schema.*
21+
import com.paligot.jsonforms.kotlin.models.uischema.*
22+
23+
val schema = Schema(
24+
properties = persistentMapOf(
25+
"email" to StringProperty(pattern = "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"),
26+
"password" to StringProperty()
27+
),
28+
required = persistentListOf("email", "password")
29+
)
30+
31+
val uiSchema = VerticalLayout(
32+
elements = persistentListOf(
33+
Control(scope = "#/properties/email", label = "Email"),
34+
Control(scope = "#/properties/password", label = "Password")
35+
)
36+
)
37+
```

‎ui/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# UI
2+
3+
This module provides the core UI logic and composable components. It is responsible for form state
4+
management, the main `JsonForm` component, and the interfaces and scopes that enable custom and
5+
platform-specific renderers.
6+
7+
## Usage
8+
9+
Add the dependency to your project:
10+
11+
```kotlin
12+
dependencies {
13+
implementation("com.paligot.jsonforms.kotlin:ui:<version>")
14+
}
15+
```
16+
17+
Import and use the main UI components in your code:
18+
19+
```kotlin
20+
import com.paligot.jsonforms.ui.*
21+
22+
val formState = rememberJsonFormState(mutableMapOf("email" to "", "password" to ""))
23+
24+
JsonForm(
25+
schema = schema,
26+
uiSchema = uiSchema,
27+
state = formState,
28+
layoutContent = { /* your layout renderer */ },
29+
stringContent = { /* your string field renderer */ },
30+
numberContent = { /* your number field renderer */ },
31+
booleanContent = { /* your boolean field renderer */ }
32+
)
33+
```

0 commit comments

Comments
 (0)