@colineapp/ui 0.2.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +73 -0
- package/package.json +4 -3
package/AGENTS.md
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
# UI package agent guide
|
|
2
|
+
|
|
3
|
+
`@colineapp/ui` is the public React component and bridge-provider package for
|
|
4
|
+
tier-2 Coline Apps. It is the app author's UI layer; it is not the platform's
|
|
5
|
+
internal component library.
|
|
6
|
+
|
|
7
|
+
## Required app setup
|
|
8
|
+
|
|
9
|
+
```tsx
|
|
10
|
+
import { createRoot } from "react-dom/client";
|
|
11
|
+
import {
|
|
12
|
+
Button,
|
|
13
|
+
ColineAppProvider,
|
|
14
|
+
useColine,
|
|
15
|
+
useColineQuery,
|
|
16
|
+
} from "@colineapp/ui";
|
|
17
|
+
import "@colineapp/ui/styles.css";
|
|
18
|
+
|
|
19
|
+
function Home() {
|
|
20
|
+
const coline = useColine();
|
|
21
|
+
const items = useColineQuery(
|
|
22
|
+
(capabilities) => capabilities.files.list({ limit: 100 }),
|
|
23
|
+
[],
|
|
24
|
+
);
|
|
25
|
+
return <Button onClick={() => items.refetch()}>Refresh</Button>;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
const root = document.getElementById("root");
|
|
29
|
+
if (root) {
|
|
30
|
+
createRoot(root).render(
|
|
31
|
+
<ColineAppProvider>
|
|
32
|
+
<Home />
|
|
33
|
+
</ColineAppProvider>,
|
|
34
|
+
);
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The package requires React 19 and ReactDOM 19 as peer dependencies. The
|
|
39
|
+
scaffold installs them for app authors. `ColineAppProvider` is mandatory
|
|
40
|
+
before using `useColine`, `useColineContext`, `useColineQuery`, or
|
|
41
|
+
`useColorScheme`; it intentionally renders nothing until the bridge connects.
|
|
42
|
+
|
|
43
|
+
## Data and sandbox rules
|
|
44
|
+
|
|
45
|
+
- All app data goes through the injected `coline.*` capability client.
|
|
46
|
+
- Do not use `fetch`, localStorage, cookies, direct API routes, or credentials
|
|
47
|
+
in a sandboxed app. Network access belongs behind `coline.net.fetch` and the
|
|
48
|
+
manifest allowlist.
|
|
49
|
+
- `useColineQuery(loader, deps)` is a small loading/error/refetch helper, not a
|
|
50
|
+
cache. Keep loaders bounded and put stable values in `deps`.
|
|
51
|
+
- Use host theme tokens and the exported components. Do not hardcode light-only
|
|
52
|
+
colors or invent a second provider.
|
|
53
|
+
|
|
54
|
+
## Component contract
|
|
55
|
+
|
|
56
|
+
The public barrel exports the provider/hooks plus accessible components such
|
|
57
|
+
as `Button`, `Card`, `Input`, `Textarea`, `Badge`, `Dialog`, `Select`,
|
|
58
|
+
`Checkbox`, `Switch`, `Tabs`, `Table`, `Skeleton`, and `Tooltip`. Check the
|
|
59
|
+
component source and declaration output before documenting a new prop.
|
|
60
|
+
|
|
61
|
+
The client bundle is built by Coline. The app submits `main.tsx` and its
|
|
62
|
+
source files; it does not submit `node_modules` or install packages in the
|
|
63
|
+
sandbox. Keep client imports limited to the scaffold dependencies and app
|
|
64
|
+
source.
|
|
65
|
+
|
|
66
|
+
## Verification and release
|
|
67
|
+
|
|
68
|
+
- Run `pnpm --filter @colineapp/ui typecheck` after component/provider changes.
|
|
69
|
+
- Keep CSS export and component export changes together.
|
|
70
|
+
- Preserve React peer dependency ranges and the `./styles.css` export.
|
|
71
|
+
- Update README examples and the scaffold skill when an app-facing contract
|
|
72
|
+
changes. The generated app must be able to use the documented API after a
|
|
73
|
+
clean `npm install`.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@colineapp/ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.1",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"sideEffects": false,
|
|
6
6
|
"exports": {
|
|
@@ -18,8 +18,8 @@
|
|
|
18
18
|
"radix-ui": "^1.4.2",
|
|
19
19
|
"super-hover": "^0.2.2",
|
|
20
20
|
"tailwind-merge": "^3.0.2",
|
|
21
|
-
"@colineapp/
|
|
22
|
-
"@colineapp/
|
|
21
|
+
"@colineapp/app-runtime": "^0.3.1",
|
|
22
|
+
"@colineapp/sdk": "^0.3.1"
|
|
23
23
|
},
|
|
24
24
|
"peerDependencies": {
|
|
25
25
|
"react": "^19.0.0",
|
|
@@ -51,6 +51,7 @@
|
|
|
51
51
|
"files": [
|
|
52
52
|
"dist",
|
|
53
53
|
"README.md",
|
|
54
|
+
"AGENTS.md",
|
|
54
55
|
"LICENSE"
|
|
55
56
|
],
|
|
56
57
|
"publishConfig": {
|