@hearthscale/app-ui 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,25 @@
+MIT License
+
+Copyright (c) 2026 Simon Wagenfuehrer
+
+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 fonts in `dist/fonts` are licensed under the SIL Open Font License 1.1
+(`dist/fonts/OFL.txt`). The Remix Icon font in `dist/remixicon` is licensed
+under the Apache License 2.0 (`dist/remixicon/License`).

package/README.md

@@ -1,3 +1,168 @@
-# Temporary Holding Version
+# @hearthscale/app-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.
+The UI kit of a Hearthscale app's view: the tokens and `hs-*` classes of the
+Hearthscale design system, React parts built from it, and the whole Remix Icon
+set. A view drawn with it looks like the rest of Hearthscale and follows the
+person's theme, colourway and colour scheme.
+
+## In a view
+
+Hearthscale loads the kit into every view an app packages: `ui.css`, with the
+tokens and the `hs-*` classes, and `remixicon.css`, with the Remix Icon font
+and its `ri-*` classes. The view's document is the theme root
+(`<html class="hs-shell hs-view" data-theme="dark">`, `light` in the light
+scheme), so you bundle no stylesheet of the kit. Write the classes:
+
+```html
+<button class="hs-button" data-variant="secondary" data-size="sm">
+  <i class="hs-icon ri-add-line"></i>New note
+</button>
+```
+
+or, in a React view, import the parts:
+
+```tsx
+import { Button, Card, Icon } from '@hearthscale/app-ui';
+
+export function Notes() {
+  return (
+    <Card>
+      <Button icon={<Icon name="add-line" size={14} />}>New note</Button>
+    </Card>
+  );
+}
+```
+
+The parts are one ES module that leaves React 19 and `@floating-ui/dom` to
+your bundle. Bundle them into your view: the host gives a packaged view the
+stylesheets and maps `@modelcontextprotocol/ext-apps` to its own copy
+(`/ui/mcp-apps.js`), so leave that one import out of the bundle.
+
+A label names its action. Where a reason is needed, give it in a tooltip
+(`useFloatingTips`), not in a line under the action.
+
+## The parts
+
+| Kind           | Parts                                                                                      |
+| -------------- | ------------------------------------------------------------------------------------------ |
+| Actions        | `Button`, `IconButton`                                                                     |
+| Surfaces       | `Card`, `SettingsCard`, `SettingsSection`, `EmptyState`, `Notice`                          |
+| Scrolling      | `OverlayScroll`                                                                            |
+| Rows           | `ListRow`, `InfoRow`, `LinkRow`, `FactRow`, `ToggleRow`                                    |
+| Fields         | `TextField`, `TextInput`, `Toggle`, `SegmentedControl`, `SettingsSearch`, `SettingsSelect` |
+| Tabs           | `SettingsTabs`                                                                             |
+| Status         | `Chip`, `StatusWord`                                                                       |
+| Text           | `PageTitle`, `Label`, `Mono`                                                               |
+| Menus and tips | `MenuSurface`, `MItem`, `MSub`, `MDivider`, `MSection`, `anchorFrom`, `useFloatingTips`    |
+| Dialogs        | `ShellConfirm`                                                                             |
+| Icons          | `Icon`                                                                                     |
+
+Each part draws the same `hs-*` classes as the same part in Hearthscale, so a
+theme reaches it as it reaches the shell.
+
+## Icons
+
+Every Remix Icon, by its name on [remixicon.com](https://remixicon.com/):
+
+```html
+<i class="hs-icon ri-mail-line"></i>
+```
+
+```tsx
+<Icon name="mail-line" size={16} />
+```
+
+The mark takes the colour of the text around it, and the font size around it
+or `size`. `hs-icon` gives it the box of its size and the states of the
+design system's drawn marks: the dim ink in a picker or a search field, and
+the press of the control it sits in. `IconName` names every icon, so your
+editor completes the names. Draw no icon by hand.
+
+Two marks are Hearthscale's own, drawn the same way: the sidebar open wide
+and folded narrow, which Hearthscale's own sidebars show on the press that
+opens and folds them. A press shows the shape the sidebar takes:
+
+```html
+<i class="hs-icon hs-glyph-side-narrow"></i>
+```
+
+```tsx
+<Icon name="side-narrow" size={16} />
+```
+
+## Tokens and classes
+
+`dist/TOKENS.md` lists every token with its dark and light value, and
+`dist/CLASSES.md` every public `hs-*` class, as do the
+[tokens](https://hearthscale.com/docs/developers/themes/tokens) and
+[classes](https://hearthscale.com/docs/developers/themes/classes) pages of
+the documentation. A view may use every class there. Give your own rules tokens for every colour,
+corner, size and duration, such as `color: var(--mut)` or
+`border-radius: var(--r-card)`, so a theme and a colourway reach your view as
+they reach the shell.
+
+## Previews and docs
+
+Outside Hearthscale, import the two sheets and give the page the root the host
+gives a view, on the plate a view sits on:
+
+```js
+import '@hearthscale/app-ui/ui.css';
+import '@hearthscale/app-ui/remixicon.css';
+```
+
+```html
+<html class="hs-shell hs-view" data-theme="dark" style="background: var(--win)"></html>
+```
+
+## The rail icon
+
+The rail shows the `icon` of your `app.json` 18 pixels square, beside
+Hearthscale's own marks. Draw it to sit among them:
+
+- **A 20 px grid.** A square `viewBox="0 0 24 24"` with the shape inside the
+  central 20 × 20, 2 units clear on every side.
+- **Monochrome.** One colour, in the weight of Remix Icon's line marks: no
+  gradient, no shadow, no text.
+- **`currentColor`.** Draw every shape in `currentColor` and set the ink once,
+  on the root. The rail shows the icon as a picture, which takes no colour from
+  the page, so give one file per scheme, the two differing in that one colour:
+  `#111111` in the light file, `#ffffff` in the dark file.
+
+```json
+"icon": { "light": "assets/icon-light.svg", "dark": "assets/icon-dark.svg" }
+```
+
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" color="#111111">
+  <path fill="currentColor" d="M5 4h14v2H5zM5 9h14v2H5zM5 14h9v2H5z" />
+</svg>
+```
+
+## Licences
+
+The code is MIT. Inter and JetBrains Mono are under the SIL Open Font License
+1.1 (`dist/fonts/OFL.txt`). The Remix Icon font, from `remixicon` 4.8.0, is
+under the Apache License 2.0 (`dist/remixicon/License`).
+
+## Building, in the Hearthscale repository
+
+`pnpm --filter @hearthscale/app-ui build` writes `dist/` from the design
+system's build and the `remixicon` package, and writes `src/icon-names.ts`
+from the font's sheet. It does not build `@hearthscale/ui`:
+`pnpm --filter @hearthscale/app-ui... build` builds both, the design system
+first. The parts come from the design system's `kit` entry
+(`packages/ui/src/kit.ts`): a part is added there, never copied here. The
+platform's build stages the sheets and fonts of this `dist/` beside the
+daemon, with the MCP Apps SDK's browser build as `mcp-apps.js`, which the
+build writes to `dist/host/` without the SDK's `console.debug` of every
+message and the package does not publish, and the
+daemon serves them to every view as `/ui/*`, so the kit a view gets and the
+files this package publishes are one build.
+`npm pack --dry-run` lists what a publish ships. `remixicon` stays at 4.8.0
+here and in `@hearthscale/ui`: its later releases carry the Remix Icon License
+v1.0 in place of the Apache License 2.0. Every Tiptap package takes one exact
+version, here and in `@hearthscale/ui`, and they move together: a Tiptap
+package of one release reads the internals of another, so a range lets an
+app's install mix two releases, and `RichTextEditor` then breaks on Markdown
+headings.