@overvis/hmi-workspace-ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, OVERVIS OÜ
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# `@overvis/hmi-workspace-ui`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React workspace hosts, Setup pages, dashboards, reports, forms and typed API bindings for Overvis
+HMI. Workspace operations require its API; the host owns authentication and account management.
+
+## Installation
+
+The simplest host is a pulled workspace: `npx overvis-hmi pull <token>` creates a project with
+matching package versions, an API proxy, and `LocalWorkspaceApp` already mounted.
+
+To install the package in your own application, add it with its peers (`react`, `react-dom`,
+`@tanstack/react-form`, `@tanstack/react-query`, `@tanstack/react-router`, `@trpc/client`,
+`@trpc/react-query`, `@trpc/server`) and import `@overvis/hmi-workspace-ui/styles.css` once for the
+shared theme and fonts. Consumer builds resolve its relative font URLs. The build tooling needs
+Node.js 22.12 or later.
+
+The package is in beta (0.x): a minor version may contain breaking changes. It shares its version
+with `@overvis/hmi-shared`, `@overvis/hmi-cli`, and `overvis-hmi`; keep them on the same version.
+
+## Entry points
+
+| Entry                    | Contents                                                     |
+| ------------------------ | ------------------------------------------------------------ |
+| `.`                      | Dashboard kit: components, hooks, and API bindings           |
+| `./ui`                   | UI primitives                                                |
+| `./host`                 | Host shell: `LocalWorkspaceApp`, workspace routes, providers |
+| `./i18n`                 | Locale initialization, translation hooks, catalogs           |
+| `./dashboard-bindings`   | Parameter binding helpers for dashboard configuration        |
+| `./parameter-values`     | Live parameter value model                                   |
+| `./styles.css`           | Host theme, utilities, and fonts                             |
+| `./styles-reference.css` | Class tokens for dashboard builds (no preflight or fonts)    |
+
+Dashboards run inside the workspace host and share its React, API clients, language, and theme. The
+host import map provides the root, `./ui`, and `./i18n`; dashboards never import `./host`.
+
+## Hosts
+
+`LocalWorkspaceApp` (from `./host`) accepts an API base URL, workspace API key, and workspace UUID
+and creates its own query, router, theme, and workspace providers. The API accepts browser requests
+only from its own web app, so proxy `/trpc` and `/static` (published dashboards, rendered reports)
+from the host's origin and pass `/`; the component appends `/trpc` itself. The key is readable by
+everyone who can open the host: keep it scoped to the workspace and its intended permissions.
+`LocalWorkspaceApp` also reads unpushed dashboard configuration from the `hmi` development server
+under `/__hmi/setup/`; a host without that server must answer those paths with 404 or its HTML
+page.
+
+To embed workspace pages in a TanStack Router host, attach `createWorkspaceRoutes(route)` under its
+`/workspace/$workspaceId` route and provide `trpc.Provider`, `QueryClientProvider`, and
+`WorkspaceHostProvider`. `createTrpcClient` and `createQueryClient` create the clients; `trpc` is
+typed on `PublicAppRouter`.
+
+## Translations
+
+Hosts await `initializeLocale()` from `./i18n` before rendering translated components, and register
+additional catalogs with `browserLocale.register` before that. `useTranslation()` and `useLocale()`
+subscribe to language changes; `await setLocale(locale)` loads every registered catalog before
+switching, and a failed load keeps the current language. Translation keys and placeholder arguments
+are checked by TypeScript against literal catalogs.
+
+## Behavior to rely on
+
+- Parameter control, value-editor, and write-sequence components confirm writes and stop at the
+  first unacknowledged step. Write results describe the command sent, not a measured value.
+- `useCounterTotals` shows counter consumption from server deltas only: missing history is "No
+  data", never 0, and a counter reset is flagged, never corrected.
+- API-backed forms keep submission inside `FormRoot`, so Enter and Save use the same validation.
+- `DashboardGraphics` keeps workspace, dashboard, and drawing UUIDs stable; concurrent saves
+  compare the revision captured when editing began. Symbol IDs starting with `hmi.` are reserved
+  for built-ins.
+- `useToast` from `./ui` records messages in the history of `MessageHistoryProvider identity`;
+  without browser storage the history is kept in memory.
+
+## Documentation and support
+
+The
+[`@overvis/hmi-workspace-ui` reference](https://docs.overvis.com/en/hmi/reference/packages/workspace-ui/)
+describes every entry, host contract, and component; the
+[Overvis documentation](https://docs.overvis.com) has the dashboard guides. Report problems through
+the [Overvis helpdesk](https://helpdesk.overvis.com).
+
+## License
+
+BSD-3-Clause; see `LICENSE`, and `THIRD_PARTY_NOTICES` for bundled styles and fonts. The Overvis
+and Overvis HMI names and the Overvis logos are trademarks of OVERVIS OÜ and are not licensed under
+it.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,151 @@
+# Third-party notices
+
+The UI components and compiled stylesheet incorporate code from shadcn/ui, distributed under the
+MIT License.
+
+Copyright (c) 2023 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+The distributed font files include Inter, licensed under the SIL Open Font License,
+Version 1.1.
+
+The complete license text is distributed as `dist/OFL-1.1.txt`.
+
+Inter: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of the Font Software,
+to use, study, copy, merge, embed, modify, redistribute, and sell modified and unmodified copies of
+the Font Software, subject to the following conditions:
+
+1. Neither the Font Software nor any of its individual components, in Original or Modified
+   Versions, may be sold by itself.
+2. Original or Modified Versions of the Font Software may be bundled, redistributed and/or sold
+   with any software, provided that each copy contains the above copyright notice and this license.
+3. No Modified Version of the Font Software may use the Reserved Font Name(s) unless explicit
+   written permission is granted by the corresponding Copyright Holder.
+4. The names of Copyright Holders or Authors may not promote, endorse, or advertise a Modified
+   Version except to acknowledge contributions or with explicit permission.
+5. The Font Software, modified or unmodified, in part or in whole, must be distributed entirely
+   under this license. This requirement does not apply to documents created with the Font Software.
+
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO ANY WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, INCLUDING ANY GENERAL, SPECIAL,
+INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER
+DEALINGS IN THE FONT SOFTWARE.
+
+The compiled stylesheet also incorporates CSS from the following packages.
+
+## tailwindcss
+
+MIT License
+
+Copyright (c) Tailwind Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## tw-animate-css
+
+MIT License
+
+Copyright (c) 2025 Wombosvideo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## uplot
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Leon Sorokin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## @xyflow/react
+
+MIT License
+
+Copyright (c) 2019-2025 webkid GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/OFL-1.1.txt

@@ -0,0 +1,93 @@
+Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter) Inter-Italic[opsz,wght].ttf: Copyright 2016 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.