@simai-studio/ui 0.0.0-stage → 5.20261019.1710

package/distr/core/contracts/ports/simai.property-view-port/1.4.0/port.json

@@ -0,0 +1,569 @@
+{
+  "schema": "simai.composite.host-port.v1",
+  "port": "simai.property-view-port",
+  "version": "1.4.0",
+  "component": "smart.property-view",
+  "element": "sf-property-view",
+  "summary": "The host seam for one object's fields shown as sections, groups and fields. The host owns the values, the arrangement, the revision, the address, the transfer of files and what opening a reference means; a group is saved as one revision by the button.",
+  "capabilities": {
+    "field-options": {
+      "summary": "Candidate records for a reference field, a page at a time with a search. A host without this capability is not broken: the field shows its current value read-only, which is what the component does when no editor can be built.",
+      "intents": [
+        "field.options"
+      ],
+      "data": [
+        "options_page"
+      ]
+    },
+    "field-upload": {
+      "summary": "Taking a file the person chose. A host without this capability is not broken: a file field shows what it already holds, read-only, which is the same arrangement as field-options.",
+      "intents": [
+        "field.upload"
+      ],
+      "data": []
+    }
+  },
+  "data": {
+    "record": {
+      "summary": "The object as the host sees it now, with its arrangement. The component holds this for rendering and never writes to it.",
+      "required": true,
+      "schema": {
+        "type": "object",
+        "required": [
+          "sections"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record_id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          },
+          "collection": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "revision": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ],
+            "description": "The revision a later write will be compared against. Reading does not require one; writing in a later port version does."
+          },
+          "sections": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "key",
+                "groups"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "key": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "label": {
+                  "type": "string"
+                },
+                "rare": {
+                  "type": "boolean"
+                },
+                "hidden": {
+                  "type": "boolean"
+                },
+                "groups": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "required": [
+                      "key",
+                      "fields"
+                    ],
+                    "additionalProperties": false,
+                    "properties": {
+                      "key": {
+                        "type": "string",
+                        "minLength": 1
+                      },
+                      "label": {
+                        "type": "string"
+                      },
+                      "rare": {
+                        "type": "boolean"
+                      },
+                      "hidden": {
+                        "type": "boolean"
+                      },
+                      "columns": {
+                        "enum": [
+                          1,
+                          2
+                        ]
+                      },
+                      "fields": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "required": [
+                            "key",
+                            "propertyType"
+                          ],
+                          "additionalProperties": false,
+                          "properties": {
+                            "key": {
+                              "type": "string",
+                              "minLength": 1
+                            },
+                            "label": {
+                              "type": "string"
+                            },
+                            "propertyType": {
+                              "type": "string",
+                              "description": "The Larena property type the renderer set is addressed by. The host supplies the type; the Framework supplies the template."
+                            },
+                            "variant": {
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            },
+                            "value": {},
+                            "unit": {
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            },
+                            "width": {
+                              "enum": [
+                                "half",
+                                "full"
+                              ]
+                            },
+                            "required": {
+                              "type": "boolean"
+                            },
+                            "rare": {
+                              "type": "boolean"
+                            },
+                            "hidden": {
+                              "type": "boolean"
+                            },
+                            "inherited": {
+                              "type": "boolean"
+                            },
+                            "hint": {
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            },
+                            "options": {
+                              "type": [
+                                "array",
+                                "null"
+                              ]
+                            },
+                            "trueText": {
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            },
+                            "falseText": {
+                              "type": [
+                                "string",
+                                "null"
+                              ]
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "address": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "Where this object lives, as the host names it. The component never constructs one: it copies this and opens this, and shows neither control when the host sends nothing. A component that invented an address would be guessing at the consumer's routing."
+          }
+        }
+      }
+    },
+    "options_page": {
+      "summary": "One page of candidates for one field, with the cursor for the next page. The component holds the page for rendering and asks again rather than caching across searches.",
+      "required": false,
+      "schema": {
+        "type": "object",
+        "required": [
+          "items"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "items": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "value",
+                "label"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "value": {
+                  "type": [
+                    "string",
+                    "integer"
+                  ]
+                },
+                "label": {
+                  "type": "string",
+                  "description": "What a person reads. The label travels with the value so the chosen record can be shown without a second read."
+                }
+              }
+            }
+          },
+          "next_cursor": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ],
+            "description": "Opaque to the component: it is sent back unchanged to ask for the next page. Absent or null means this is the last page."
+          },
+          "total": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          }
+        }
+      }
+    }
+  },
+  "intents": {
+    "record.load": {
+      "summary": "Read one object with its arrangement. The only intent in this version.",
+      "event": "sf-property-view-state",
+      "payload": {
+        "type": "object",
+        "required": [
+          "record_id",
+          "collection",
+          "reason"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record_id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          },
+          "collection": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why the component is asking: connected, host-connected, record-id-changed or requested. For the host's own logging; it must not change the answer."
+          }
+        }
+      },
+      "carries_revision": false,
+      "answers": [
+        "applied",
+        "refused",
+        "unavailable"
+      ]
+    },
+    "group.save": {
+      "summary": "Save the fields a person changed in one group, as one revision. Sent only when the save button is pressed -- never on blur and never per field.",
+      "event": "sf-property-view-state",
+      "payload": {
+        "type": "object",
+        "required": [
+          "record_id",
+          "collection",
+          "section",
+          "group",
+          "values",
+          "revision"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record_id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          },
+          "collection": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "section": {
+            "type": "string",
+            "minLength": 1
+          },
+          "group": {
+            "type": "string",
+            "minLength": 1
+          },
+          "values": {
+            "type": "object",
+            "description": "Only the fields whose value the person changed, keyed by field key. A field the person did not touch is absent, so a save cannot overwrite what another save changed meanwhile.",
+            "additionalProperties": true
+          },
+          "revision": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ],
+            "description": "The revision the read carried. The host compares and sets; a stale one is a conflict, never a silent overwrite."
+          }
+        }
+      },
+      "carries_revision": true,
+      "answers": [
+        "applied",
+        "conflict",
+        "refused",
+        "unavailable"
+      ]
+    },
+    "field.options": {
+      "summary": "Read one page of candidate records for a reference field, optionally narrowed by a search. Never a write.",
+      "event": "sf-property-view-state",
+      "payload": {
+        "type": "object",
+        "required": [
+          "record_id",
+          "collection",
+          "field",
+          "cursor",
+          "search"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record_id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          },
+          "collection": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "field": {
+            "type": "string",
+            "minLength": 1
+          },
+          "cursor": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ],
+            "description": "The next_cursor of the previous answer, or null for the first page. The component never constructs one."
+          },
+          "search": {
+            "type": "string",
+            "description": "What the person typed. The search belongs to the host: the component does not filter the page it was given, because the page is not the whole set."
+          }
+        }
+      },
+      "carries_revision": false,
+      "answers": [
+        "applied",
+        "refused",
+        "unavailable"
+      ],
+      "capability": "field-options"
+    },
+    "field.upload": {
+      "summary": "Take one file the person chose and store it. Answered with the stored file in the same shape the field reads, so the view needs no second read.",
+      "event": "sf-property-view-state",
+      "payload": {
+        "type": "object",
+        "required": [
+          "record_id",
+          "collection",
+          "field",
+          "file"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record_id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ]
+          },
+          "collection": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "field": {
+            "type": "string",
+            "minLength": 1
+          },
+          "file": {
+            "description": "The File the person chose, passed as it is. Not a data URL and not base64: the host decides how it travels, and a component that encoded it would double the bytes of every upload to no purpose."
+          }
+        }
+      },
+      "carries_revision": false,
+      "answers": [
+        "applied",
+        "refused",
+        "unavailable"
+      ],
+      "capability": "field-upload"
+    },
+    "record.open": {
+      "summary": "The person activated a reference value. What to open, and where, is the host's: it may push another panel onto the stack, route to a full page, or refuse.",
+      "event": "sf-property-view-open-record",
+      "payload": {
+        "type": "object",
+        "required": [
+          "record_id",
+          "collection",
+          "field",
+          "value"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "record_id": {
+            "type": [
+              "string",
+              "integer",
+              "null"
+            ],
+            "description": "The object the person was looking at, not the one being opened."
+          },
+          "collection": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "field": {
+            "type": "string",
+            "minLength": 1
+          },
+          "value": {
+            "type": "object",
+            "required": [
+              "value"
+            ],
+            "additionalProperties": true,
+            "properties": {
+              "value": {
+                "type": [
+                  "string",
+                  "integer"
+                ]
+              },
+              "label": {
+                "type": "string"
+              },
+              "href": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              }
+            },
+            "description": "The reference as the field holds it. The component passes it on and decides nothing: a composite that followed the href itself would be routing for the consumer, and a composite that opened a window itself would be deciding whether a half-edited window may be covered."
+          }
+        }
+      },
+      "carries_revision": false,
+      "answers": [
+        "applied",
+        "refused",
+        "unavailable"
+      ]
+    }
+  },
+  "settings": {
+    "layers": [
+      "package",
+      "shared",
+      "personal"
+    ],
+    "shared_only_fields": [],
+    "reset": {
+      "semantics": "compare-and-set",
+      "summary": "Resetting a layer is a write against its revision, never a deletion. Declared here because the layer rules are already decided; no settings intent exists in this version."
+    },
+    "target": {
+      "kinds": [
+        "personal",
+        "shared"
+      ],
+      "carries_revision": true
+    },
+    "fields": {
+      "summary": "Per-field view settings a layer will carry when the view can be configured: order, group, section, template variant, width, hint and visibility. Not writable in this version.",
+      "writable_in": "1.1.0"
+    }
+  },
+  "conformance": {
+    "kit": "kit",
+    "sha256": "c6f8df678c75a6c9f60fba3d28071d81ca64bd09561bd2a1fc336906138b5e25",
+    "cases": 17
+  },
+  "compatibility": {
+    "previous_major": null,
+    "supported_until": null,
+    "recheck": [
+      "the answer carries the object and its arrangement, not a flat list of values",
+      "a refused read is explained rather than rendered as empty",
+      "a late answer is dropped rather than drawn over the current object",
+      "rare fields arrive declared, and hiding them changes no value",
+      "the host supplies the property type and never the component to draw it with",
+      "a save carries only the fields the person changed",
+      "a stale revision is answered with a conflict rather than an overwrite",
+      "field errors come back keyed by field and are shown under their own field",
+      "nothing is saved on blur or per field",
+      "candidate records are a page with a cursor, never the whole set",
+      "the search reaches the host rather than filtering the page already loaded",
+      "a chosen record the page does not hold is still shown and still written",
+      "a host without the field-options capability shows the value read-only rather than an empty control",
+      "the address of a window is the host's, and a component without one offers neither copying nor opening",
+      "a file is taken by the host, which reports its own progress; the component times nothing",
+      "removing a stored file is a value change saved by the button, never an upload intent",
+      "the stored file comes back in the shape the field reads, so no second read is needed",
+      "activating a reference asks the host what to open rather than following a link",
+      "a window left half-edited underneath another keeps its unsaved changes, because each window is its own element"
+    ]
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/field-presentation-keys-are-declared.json

@@ -0,0 +1,12 @@
+{
+  "id": "field-presentation-keys-are-declared",
+  "intent": "record.load",
+  "summary": "A field carries the words and limits its control needs -- the call to action and the readable formats of a file field, the accept list its dialog filters by, a placeholder, a search placeholder, a badge appearance, a readonly mark. All of them are the host's, and an answer carrying them is applied.",
+  "given": {"capabilities": ["field-upload"]},
+  "when": {"intent": "record.load", "payload": {"record_id": "record-1", "collection": "pages", "reason": "connected"}},
+  "then": {
+    "answer": "applied",
+    "answer_must_include": ["record"],
+    "note": "This case exists because the field schema is closed. A host that validates its own answers against this port was refused for sending uploadText, formats and accept -- keys the renderer set has always read but the port never declared, which is the port lying about the seam rather than the host getting it wrong. A field control with no words of its own falls back to the component's default, and a file control's default names image formats, which is wrong for a field that takes any file."
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/group-save-applied-is-one-revision.json

@@ -0,0 +1,16 @@
+{
+  "id": "group-save-applied-is-one-revision",
+  "intent": "group.save",
+  "summary": "Pressing save sends one intent carrying only the changed fields, and the host answers with the object at its new revision.",
+  "given": {"capabilities": []},
+  "when": {
+    "intent": "group.save",
+    "payload": {"record_id": "record-1", "collection": "pages", "section": "main", "group": "about",
+                "values": {"title": "Новое название"}, "revision": "7"}
+  },
+  "then": {
+    "answer": "applied",
+    "answer_must_include": ["record"],
+    "note": "One press, one intent, one revision. A field the person did not touch is absent from values, so a save cannot overwrite what another save changed meanwhile."
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/group-save-field-errors-are-refused.json

@@ -0,0 +1,16 @@
+{
+  "id": "group-save-field-errors-are-refused",
+  "intent": "group.save",
+  "summary": "Values the host will not accept come back refused with errors keyed by field, and each error is shown under its own field.",
+  "given": {"capabilities": []},
+  "when": {
+    "intent": "group.save",
+    "payload": {"record_id": "record-1", "collection": "pages", "section": "main", "group": "about",
+                "values": {"title": "", "count": "many"}, "revision": "7"}
+  },
+  "then": {
+    "answer": "refused",
+    "answer_must_include": ["errors"],
+    "note": "errors is keyed by field key, so the component can place each message under the field it belongs to. A single sentence for the whole group leaves a person hunting for which field is wrong."
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/group-save-stale-revision-is-a-conflict.json

@@ -0,0 +1,16 @@
+{
+  "id": "group-save-stale-revision-is-a-conflict",
+  "intent": "group.save",
+  "summary": "A save against a revision the host has moved past is a conflict, never a silent overwrite.",
+  "given": {"capabilities": []},
+  "when": {
+    "intent": "group.save",
+    "payload": {"record_id": "record-1", "collection": "pages", "section": "main", "group": "about",
+                "values": {"title": "Новое название"}, "revision": "6"}
+  },
+  "then": {
+    "answer": "conflict",
+    "answer_must_include": ["reason"],
+    "note": "The component keeps what the person typed and says the object moved. Answering applied here would lose somebody else's save without anyone being told."
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/load-applied-carries-the-object.json

@@ -0,0 +1,12 @@
+{
+  "id": "load-applied-carries-the-object",
+  "intent": "record.load",
+  "summary": "An applied read carries the object with its sections, groups and fields, and the revision a later write will be compared against.",
+  "given": {"capabilities": []},
+  "when": {"intent": "record.load", "payload": {"record_id": "record-1", "collection": "pages", "reason": "connected"}},
+  "then": {
+    "answer": "applied",
+    "answer_must_include": ["record"],
+    "note": "record.sections is required even when there is one section: the arrangement is the host's, and a flat list of values would make the component invent one."
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/load-late-answer-is-dropped.json

@@ -0,0 +1,15 @@
+{
+  "id": "load-late-answer-is-dropped",
+  "intent": "record.load",
+  "summary": "Two reads in flight: the answer to the earlier one is dropped and never drawn over the later object.",
+  "given": {"capabilities": []},
+  "when": {
+    "intent": "record.load",
+    "payload": {"record_id": "record-2", "collection": "pages", "reason": "record-id-changed"},
+    "after": {"intent": "record.load", "payload": {"record_id": "record-1", "collection": "pages", "reason": "connected"}}
+  },
+  "then": {
+    "answer": "applied",
+    "note": "The host may answer in either order. The component counts its own asks and renders only the newest, so a slow first answer cannot replace the object a person is now looking at."
+  }
+}

package/distr/core/contracts/ports/simai.property-view-port/1.5.0/kit/cases/load-refused-is-explained.json

@@ -0,0 +1,12 @@
+{
+  "id": "load-refused-is-explained",
+  "intent": "record.load",
+  "summary": "A read the host will not serve is refused with a reason, and the component shows the refusal rather than an empty object.",
+  "given": {"capabilities": []},
+  "when": {"intent": "record.load", "payload": {"record_id": "record-forbidden", "collection": "pages", "reason": "requested"}},
+  "then": {
+    "answer": "refused",
+    "answer_must_include": ["reason"],
+    "note": "An empty arrangement and a refused read look identical on screen unless the refusal is said out loud, and the second is the one a person can act on."
+  }
+}