@colineapp/ui 0.3.1 → 0.4.1

package/AGENTS.md

@@ -58,10 +58,9 @@ as `Button`, `Card`, `Input`, `Textarea`, `Badge`, `Dialog`, `Select`,
 `Checkbox`, `Switch`, `Tabs`, `Table`, `Skeleton`, and `Tooltip`. Check the
 component source and declaration output before documenting a new prop.
 
-The client bundle is built by Coline. The app submits `main.tsx` and its
-source files; it does not submit `node_modules` or install packages in the
-sandbox. Keep client imports limited to the scaffold dependencies and app
-source.
+The CLI bundles `main.tsx`, installed client dependencies, and imported CSS.
+Coline rebuilds the uploaded artifact; the sandbox does not install packages.
+Browser-compatible npm dependencies can be added to the app package.
 
 ## Verification and release
 
@@ -71,3 +70,45 @@ source.
 - Update README examples and the scaffold skill when an app-facing contract
   changes. The generated app must be able to use the documented API after a
   clean `npm install`.
+
+## SDK 0.4 / CLI 2.4 workflow
+
+Run `coline-app check` before pushing: it checks types, the manifest, hosted logic,
+and the React bundle without uploading. `dev --internal` updates one development
+version; install it in the workspace and reload after changes. The CLI bundles
+from the app's installed dependencies and preserves imported CSS and inline assets.
+CLI 2.5 compiles app-specific Tailwind v4 and ordinary CSS automatically.
+Import UI styles, then app.css; use complete class names. Local `preview` uses
+the public test workspace and sandbox bridge, requires no credentials, and can
+capture light/dark/mobile/error states with `--screenshots <directory>`.
+
+The starter includes a React home and editor, tree mobile fallback, and a tool.
+Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool
+from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits.
+Homes/editors can write within grants; previews and server render handlers cannot.
+`createTestWorkspace(app).client()` tests the interactive contract and
+`grantedPermissions` simulates revoked consent.
+
+New `tasks`, `calendar`, `messages`, and `references` capabilities require their
+explicit manifest permissions and retain the invoking user's workspace access.
+Use `files.list({ scope: "workspace" })` for shared files; document writes stay
+with the owning app. Collections are install-private. Code integration and a
+native mobile React runtime are separate work.
+
+`src/live-collection.ts` wraps the SDK's canonical live-record implementation.
+Keep state/conflict/sync logic in the SDK; React owns only subscriptions and
+lifecycle. Inline serializable query objects must not restart the view on each
+render. React Strict Mode cleanup/start must remain supported. Never infer record
+permission from optimistic state or broadcast private fields to an install room.
+
+## UI 0.4.1 defaults
+
+Use `Tabs` / `TabsList` / `TabsTrigger` / `TabsContent` for app views. The raised
+sliding selection and content transition are automatic. Do not recreate tab
+buttons or choose the opt-in line variant for standard Coline navigation.
+Use `FilterMenu` for value filters, and `DropdownMenu` for actions. Both use the
+canonical Coline menu surface and highlight. `pnpm check:parity` enforces the
+vendored dropdown implementation; `pnpm sync:platform` refreshes it.
+Keep animation CSS in the package, respect reduced motion, and verify controls
+in a portalled dialog as well as on the page. A form submit button needs explicit
+`type="submit"`. Do not restyle shared controls with app-specific CSS.

package/README.md

@@ -64,3 +64,87 @@ Used inside a Coline App's react-tier surface (`{ tier: "react", entry:
 Full guides at [coline.app/developers/docs](https://coline.app/developers/docs).
 
 MIT © Coline
+
+## SDK 0.4 / CLI 2.5 workflow
+
+Run `coline-app check` before pushing: it checks types, the manifest, hosted logic,
+and the React bundle without uploading. `dev --internal` updates one development
+version; install it in the workspace and reload after changes. The CLI bundles
+from the app's installed dependencies and preserves imported CSS and inline assets.
+App-specific Tailwind v4 utilities compile automatically with CLI 2.5. Import
+`@colineapp/ui/styles.css` and then `./app.css`; use complete class names.
+
+The starter includes a React home and editor, tree mobile fallback, and a tool.
+Use `coline.tools.invoke` or `actions.invokeTool` to run the same declared tool
+from UI that Kairo runs. Save with `expectedVersion` to detect concurrent edits.
+Homes/editors can write within grants; previews and server render handlers cannot.
+`createTestWorkspace(app).client()` tests the interactive contract and
+`grantedPermissions` simulates revoked consent.
+
+New `tasks`, `calendar`, `messages`, and `references` capabilities require their
+explicit manifest permissions and retain the invoking user's workspace access.
+Use `files.list({ scope: "workspace" })` for shared files; document writes stay
+with the owning app. Collections are install-private. Code integration and a
+native mobile React runtime are separate work.
+
+### Live data
+
+`useLiveCollection<RecordType>("collection", { where, orderBy, limit })` returns
+`records`, `pending`, `status`, `error`, `nextCursor`, `insert`, `update`, `delete`,
+`setAccess`, and `refresh`. Inline query objects are supported. Mutations update
+local UI immediately and reject on conflicts or permission failures; catch their
+promises to present the error. The hook owns subscription cleanup and reconnect
+recovery. Use filtered/paged views (at most 200 records), not an entire workspace
+in one hook. Structured-record sync does not imply CRDT text editing or offline
+write persistence.
+
+## Screen patterns
+
+Use `AppPage` and `PageToolbar` for consistent hierarchy, `RecordTable` with
+`SplitView`/`DetailPanel` for queues, `Board`/`BoardColumn`/`BoardCard` for stages,
+and `SettingsSection` for configuration. `EmptyState`, `AppErrorState`,
+`AppLoadingState`, and `StatusBadge` cover common states. Their CSS ships in
+`@colineapp/ui/styles.css`; they require no app-side utility generation.
+
+Patterns compose around your domain and capabilities. They do not supply data,
+routing, drag-and-drop, or persistence. `RecordTable` provides a first-cell button
+when `onOpen` is set (don't nest a second control there); secondary columns hide
+at narrow widths. Split details stack on mobile; the app owns focus management.
+See the scaffold's `examples/` for complete interactive references.
+
+## Shared controls and motion (0.4.1)
+
+`Tabs` uses the same raised selection as Coline and Upstream. Selection springs
+and content transitions are automatic; no indicator or animation wrapper is
+required. Each tabs group owns its indicator so multiple groups never collide.
+`TabsIndicator` remains available for existing custom compositions.
+
+```tsx
+<Tabs defaultValue="inbox">
+  <TabsList aria-label="Views">
+    <TabsTrigger value="inbox">Inbox</TabsTrigger>
+    <TabsTrigger value="roadmap">Roadmap</TabsTrigger>
+  </TabsList>
+  <TabsContent value="inbox">{/* Inbox */}</TabsContent>
+  <TabsContent value="roadmap">{/* Roadmap */}</TabsContent>
+</Tabs>
+<FilterMenu
+  aria-label="Filter by status"
+  value={status}
+  onValueChange={setStatus}
+  options={[{ value: "all", label: "All statuses" }, { value: "planned", label: "Planned" }]}
+/>
+```
+
+`FilterMenu` composes the exact Coline `DropdownMenu` radio group, surface, and
+sliding highlight. Use `DropdownMenu` directly for action menus. `PageToolbar`
+is borderless. `RecordTable` uses separated, rounded selection/hover rows.
+Dialogs and menus include their animation CSS; the provider respects reduced
+motion, including portals. Buttons default to `type="button"`; use
+`type="submit"` for a form's submit action.
+
+Use component defaults rather than copying their CSS into the app. Custom CSS
+variables scoped to `AppPage` do not reach portalled dialogs/menus. Keep decorative
+app variables at `:root` when they must cross portals, and retain host theme tokens.
+App bundles include their dependencies: upgrade, rebuild and push to adopt a UI
+release. Updating npm does not rewrite already-published app bundles.

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { ClassValue } from 'clsx';
 import * as React$1 from 'react';
 import { SandboxContext } from '@colineapp/app-runtime';
-import { ColineCapabilities } from '@colineapp/sdk/v2';
+import * as _colineapp_sdk_v2 from '@colineapp/sdk/v2';
+import { ColineCapabilities, ColineRecordQuery, LiveCollectionOptions } from '@colineapp/sdk/v2';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { Checkbox as Checkbox$1, Dialog as Dialog$1, DropdownMenu as DropdownMenu$1, Label as Label$1, Popover as Popover$1, Progress as Progress$1, Select as Select$1, Separator as Separator$1, Slider as Slider$1, Switch as Switch$1, Tabs as Tabs$1, Toggle as Toggle$1, Tooltip as Tooltip$1 } from 'radix-ui';
@@ -10,7 +11,7 @@ declare function cn(...inputs: ClassValue[]): string;
 
 declare function ColineAppProvider({ children }: {
     children: React$1.ReactNode;
-}): React$1.JSX.Element | null;
+}): React$1.JSX.Element;
 declare function useColine(): ColineCapabilities;
 declare function useColineContext(): SandboxContext;
 declare function useColorScheme(): "light" | "dark";
@@ -167,21 +168,21 @@ declare function TableHead({ className, ...props }: React$1.ComponentProps<"th">
 declare function TableCell({ className, ...props }: React$1.ComponentProps<"td">): React$1.JSX.Element;
 declare function TableCaption({ className, ...props }: React$1.ComponentProps<"caption">): React$1.JSX.Element;
 
-/** Shared spring for tab pill + trigger layout — keep in sync wherever `layout` runs alongside `TabsIndicator`. */
+/** Same raised selection and spring as Coline and Upstream navigation. */
 declare const TABS_LAYOUT_SPRING: {
     type: "spring";
     stiffness: number;
     damping: number;
     mass: number;
 };
-declare function Tabs({ className, orientation, ...props }: React$1.ComponentProps<typeof Tabs$1.Root>): React$1.JSX.Element;
+declare function Tabs({ className, orientation, value, defaultValue, onValueChange, ...props }: React$1.ComponentProps<typeof Tabs$1.Root>): React$1.JSX.Element;
 declare const tabsListVariants: (props?: ({
     variant?: "default" | "line" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare function TabsList({ className, variant, ...props }: React$1.ComponentProps<typeof Tabs$1.List> & VariantProps<typeof tabsListVariants>): React$1.JSX.Element;
-declare function TabsTrigger({ className, ...props }: React$1.ComponentProps<typeof Tabs$1.Trigger>): React$1.JSX.Element;
-/** Animated sliding pill indicator for TabsList (Apple-style). */
-declare function TabsIndicator({ className, layoutId, }: {
+declare function TabsTrigger({ className, children, value, asChild, ...props }: React$1.ComponentProps<typeof Tabs$1.Trigger>): React$1.JSX.Element;
+/** Optional customization; the raised indicator is included automatically. */
+declare function TabsIndicator({ className, layoutId }: {
     className?: string;
     layoutId?: string;
 }): React$1.JSX.Element;
@@ -200,4 +201,113 @@ declare function Tooltip({ ...props }: React$1.ComponentProps<typeof Tooltip$1.R
 declare function TooltipTrigger({ ...props }: React$1.ComponentProps<typeof Tooltip$1.Trigger>): React$1.JSX.Element;
 declare function TooltipContent({ className, sideOffset, children, ...props }: React$1.ComponentProps<typeof Tooltip$1.Content>): React$1.JSX.Element;
 
-export { Badge, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, ColineAppProvider, type ColineQueryState, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, Input, Label, Popover, PopoverAnchor, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger, Progress, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Skeleton, Slider, Switch, TABS_LAYOUT_SPRING, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, Toggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, cn, tabsListVariants, toggleVariants, useColine, useColineContext, useColineQuery, useColorScheme };
+/** Inline query objects are safe: equivalent inputs retain the same live view. */
+declare function useLiveCollection<T extends Record<string, unknown>>(name: string, query?: ColineRecordQuery<T>, options?: LiveCollectionOptions): {
+    insert: (data: T, access?: _colineapp_sdk_v2.ColineRecordAccess) => Promise<_colineapp_sdk_v2.ColineRecordEnvelope<T> | null>;
+    update: (id: string, patch: Partial<T>) => Promise<_colineapp_sdk_v2.ColineRecordEnvelope<T> | null>;
+    delete: (id: string) => Promise<_colineapp_sdk_v2.ColineRecordEnvelope<T> | null>;
+    setAccess: (id: string, access: _colineapp_sdk_v2.ColineRecordAccess) => Promise<_colineapp_sdk_v2.ColineRecordEnvelope<T> | null>;
+    refresh: () => Promise<void>;
+    records: readonly _colineapp_sdk_v2.ColineRecordEnvelope<T>[];
+    nextCursor: string | null;
+    status: "loading" | "ready" | "syncing" | "error";
+    pending: number;
+    error: Error | null;
+};
+
+declare function AppPage({ title, description, eyebrow, actions, children, width, className, }: {
+    title: string;
+    description?: React$1.ReactNode;
+    eyebrow?: React$1.ReactNode;
+    actions?: React$1.ReactNode;
+    children: React$1.ReactNode;
+    width?: "wide" | "reading";
+    className?: string;
+}): React$1.JSX.Element;
+declare function PageToolbar({ children, label, className, }: {
+    children: React$1.ReactNode;
+    label?: string;
+    className?: string;
+}): React$1.JSX.Element;
+declare function EmptyState({ title, description, action, icon, }: {
+    title: string;
+    description?: React$1.ReactNode;
+    action?: React$1.ReactNode;
+    icon?: React$1.ReactNode;
+}): React$1.JSX.Element;
+declare function AppErrorState({ message, onRetry }: {
+    message: string;
+    onRetry?: () => void;
+}): React$1.JSX.Element;
+declare function AppLoadingState({ label, rows, }: {
+    label?: string;
+    rows?: number;
+}): React$1.JSX.Element;
+declare function StatusBadge({ children, tone, }: {
+    children: React$1.ReactNode;
+    tone?: "neutral" | "info" | "success" | "warning" | "danger";
+}): React$1.JSX.Element;
+declare function SplitView({ list, detail, label, }: {
+    list: React$1.ReactNode;
+    detail?: React$1.ReactNode;
+    label?: string;
+}): React$1.JSX.Element;
+declare function DetailPanel({ title, subtitle, onClose, children, actions, }: {
+    title: string;
+    subtitle?: React$1.ReactNode;
+    onClose?: () => void;
+    children: React$1.ReactNode;
+    actions?: React$1.ReactNode;
+}): React$1.JSX.Element;
+interface RecordColumn<T> {
+    key: string;
+    label: string;
+    render: (record: T) => React$1.ReactNode;
+    secondary?: boolean;
+    align?: "start" | "end";
+}
+declare function RecordTable<T>({ records, columns, rowKey, onOpen, label, empty, }: {
+    records: readonly T[];
+    columns: readonly RecordColumn<T>[];
+    rowKey: (record: T) => string;
+    onOpen?: (record: T) => void;
+    label?: string;
+    empty?: React$1.ReactNode;
+}): React$1.JSX.Element;
+declare function Board({ children, label, }: {
+    children: React$1.ReactNode;
+    label?: string;
+}): React$1.JSX.Element;
+declare function BoardColumn({ title, count, children, action, }: {
+    title: string;
+    count?: number;
+    children: React$1.ReactNode;
+    action?: React$1.ReactNode;
+}): React$1.JSX.Element;
+declare function BoardCard({ title, children, footer, onOpen, }: {
+    title: string;
+    children?: React$1.ReactNode;
+    footer?: React$1.ReactNode;
+    onOpen?: () => void;
+}): React$1.JSX.Element;
+declare function SettingsSection({ title, description, children, }: {
+    title: string;
+    description?: string;
+    children: React$1.ReactNode;
+}): React$1.JSX.Element;
+
+/** A value picker using the same dropdown and sliding highlight as Coline. */
+declare const FilterMenu: React$1.ForwardRefExoticComponent<{
+    value: string;
+    options: readonly {
+        value: string;
+        label: string;
+        disabled?: boolean;
+    }[];
+    onValueChange: (value: string) => void;
+    "aria-label": string;
+    disabled?: boolean;
+    className?: string;
+} & React$1.RefAttributes<HTMLButtonElement>>;
+
+export { AppErrorState, AppLoadingState, AppPage, Badge, Board, BoardCard, BoardColumn, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, ColineAppProvider, type ColineQueryState, DetailPanel, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuPortal, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, EmptyState, Field, FieldContent, FieldDescription, FieldError, FieldGroup, FieldLabel, FieldLegend, FieldSeparator, FieldSet, FieldTitle, FilterMenu, Input, Label, PageToolbar, Popover, PopoverAnchor, PopoverContent, PopoverDescription, PopoverHeader, PopoverTitle, PopoverTrigger, Progress, type RecordColumn, RecordTable, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, SettingsSection, Skeleton, Slider, SplitView, StatusBadge, Switch, TABS_LAYOUT_SPRING, Table, TableBody, TableCaption, TableCell, TableFooter, TableHead, TableHeader, TableRow, Tabs, TabsContent, TabsIndicator, TabsList, TabsTrigger, Textarea, Toggle, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, badgeVariants, buttonVariants, cn, tabsListVariants, toggleVariants, useColine, useColineContext, useColineQuery, useColorScheme, useLiveCollection };