Write specifications

src/specifications/README.md

@@ -0,0 +1,7 @@
+# Specifications
+
+Zap aims to support various programming languages and runtimes. Therefore, there is a need to provide a consistent interface across all implementations. This section defines the standard interfaces of Zap.
+
+This specification defines a general interface for implementations and is not based on any specific programming language. Therefore, please refer to the API documentation of each implementation for details such as specific function names, property names, and parameters.
+
+Among the interfaces presented in this specification, there are those that must be implemented, those that are recommended for implementation under specific circumstances, and optional ones. In such cases, keywords are used in accordance with the criteria suggested in [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119).

src/specifications/client-and-server.md

@@ -0,0 +1,28 @@
+# Client and Server
+
+
+## `ZapClient`
+
+A client sends data to server.
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `server_address` | An IP address of the device running `ZapServer`. |
+| function | `send(obj: Zapable): void` | Send given `Zapable` object to the server. <hr> `obj`: An object to send. |
+| function | `stop(): void` | Close the socket. |
+
+## `ZapServer`
+
+A server receives data from client. The 'open function' refers to a callback function that users SHOULD override when declaring a ZapServer object to define its behavior. Refer to the [Resources](./resources.md) section for information on the parameters of each open function.
+
+| type | signature | description |
+|------|-----------|-------------|
+| function | `listen(port: int): void` | Start listening the transmitted data from clients on the given port. <hr> `port`: A port number for receiving data (default: `65500`).  |
+| function | `stop(): void` | Stop listening to clients. |
+| open function | `onAccelerometerChanged(id: string, x: float, y: float, z: float): void` | A callback function called whenever accelerometer sensor data is received. |
+| open function | `onUIEventReceived(id: string, ui_id: string, event: ZapUiEvent.Event, value: string?): void` | A callback function called whenever UI event data is received. |
+| open function | `onTextReceived(id: string, str: string, charset): void` | A callback function called whenever text data is received.|
+
+The server implementation, upon receiving a datagram, MUST reference the `ZapHeader` to identify the resource and then invoke the corresponding callback function for that resource. For detailed specifications on supported resources, please refer to [Resources](./resources.md) section.
+
+It is RECOMMENDED to implement throwing a "Not yet implemented" exception if the callback function is not defined and the corresponding resource data is received.

src/specifications/models.md

@@ -0,0 +1,34 @@
+# Models
+
+## `ZapDatagram`
+
+A protocol defined on top of datagrams for client and server to exchange `Zapable` data.
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `header: ZapHeader` | A header part. |
+| property | `payload: ZapPayload` | A payload part. |
+| function | `toString(): string` | Compose a string to send with the header and payload. The composed string MUST be formatted to `header;payload`. |
+| function | `from(str: string): ZapDatagram` | Convert the given string in received datagram to `ZapDatagram`. <hr> `str`: A string to convert that MUST be formatted as `header;payload`. |
+
+### `ZapHeader`
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `id: string` | An ID of the client. |
+| property | `resource: ZapResource` | A resource type of the payload. It indicates a format of payload. |
+| function | `toString(): string` | Convert `ZapHeader` to string and return it. It MUST be formatted as `id,resource`. |
+
+### `ZapPayload`
+
+A typealias for string type.
+
+## `interface Zapable`
+
+An interface for data exchange through Zap. Data objects exchanged via Zap MUST implement this interface. If an object can be transmitted through Zap, it can be referred to as "Zapable".
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `resource: ZapResource` | A resource type of the object. |
+| function | `toPayload(): ZapPayload` | Convert `Zapable` to `ZapPayload` and return it. |
+| static function | `from(obj: ZapPayload): Zapable` | Converts and returns `Zapable` object from `ZapPayload`. If possible, it is RECOMMENDED to separate it into `interface DeZapable` to enforce implementation. <hr> `obj`: A payload object to convert to `Zapable` object.  |

src/specifications/resources.md

@@ -0,0 +1,47 @@
+# Resources
+
+## `enum ZapResource`
+
+A registry of resources supported by Zap and their identification values.
+
+| property | value | description |
+|------|-----------|-------------|
+| `ACCELEROMETER` | `ACC` | A data measured by an accelerometer sensor. |
+| `UI_EVENT` | `UIE` | A data related to event raised by the user interface. |
+| `TEXT` | `TXT` | A simple text data. |
+
+## `ZapText`
+
+Represent simple text.
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `str: string` | Just string. |
+| property | `charset` | A character set of `str`. (default: `UTF-8`) |
+
+## `ZapAccelerometer`
+
+Represent values measured by accelerometer sensor.
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `x: float` | Acceleration force along the x axis. (m/s²) |
+| property | `y: float` | Acceleration force along the y axis. (m/s²) |
+| property | `z: float` | Acceleration force along the z axis. (m/s²) |
+
+## `ZapUiEvent`
+
+Represent data related to event raised by the user interface.
+
+| type | signature | description |
+|------|-----------|-------------|
+| property | `ui_id: string` | An identifier for the UI. |
+| property | `event: ZapUiEvent.Event` | A type of event occurring for the UI. |
+| property | `value: string?` | A value changed due to the event. (optional) |
+
+### `Event`
+
+| property | value | description |
+|------|-----------|-------------|
+| `CLICK_DOWN` | `CLICK_DOWN` | An event triggered when a click (or touch) is initiated on the UI. |
+| `CLICK_UP` | `CLICK_UP` | An event triggered when a click (or touch) on the UI has ended. |

src/styles.css

@@ -15,3 +15,7 @@ table thead th {
   border: 1px #000 solid;
   background-color: #efefef;
 }
+
+table td hr {
+  color: #efefef;
+}