@groveback/ui 0.1.1 → 0.3.0

package/README.md

@@ -14,7 +14,14 @@ npm install @groveback/ui
 bun add @groveback/ui
 ```
 
-React 18 or 19 is a peer dependency. The components are styled with Tailwind utility classes, so a Tailwind setup is assumed.
+React 18 or 19 is a peer dependency. The components are styled with Tailwind utility classes and ship no CSS of their own, so your app's Tailwind (v4) build has to scan them — one line in your CSS does it:
+
+```css
+@import "tailwindcss";
+@import "@groveback/ui/tailwind.css";
+```
+
+That file carries the `@source` pointing at the package's own bundle, so it works from any install layout. Dark mode follows the viewer's `prefers-color-scheme`, which is Tailwind's default.
 
 ## Usage
 
@@ -69,15 +76,43 @@ A relation field stores a document id. Pass `resolveRelation` and a `display` hi
 
 The picker loads a bounded first page and filters in memory, and it tells the user when the list is truncated — the data API has no text search to delegate to, and silently hiding matches would be worse than saying so.
 
+### The routing shell lives here, not in your repo
+
+`grove gen --ui` writes `routes.tsx` as a table — `ROUTES`, one entry per Studio screen — and a one-line `GroveRoutes` that mounts it on this package's shell:
+
+```tsx
+import { GroveRoutes } from './routes'; // generated
+import { SignIn } from '@groveback/ui';
+import { createGrove } from './grove';
+
+const grove = createGrove();
+
+export default function App() {
+  return (
+    <SignIn auth={grove.auth}>
+      <GroveRoutes />
+    </SignIn>
+  );
+}
+```
+
+`GroveRoutes` matches the current URL against the table (specific routes ahead of parameterised ones), pushes history on navigation, and provides the context the primitives dispatch through. The generated mount already passes `locale` (the viewer's language when the document has it — `detectLocale`) and `callEndpoint` (custom-endpoint actions run through `grove.client.run`, so they carry the session). Pass `context={{ currency, confirm, … }}` for the rest, `fallback` for the unmatched case, and `children` for chrome that should render on every screen. With no `fallback`, the root with no home screen shows an index of the document's pages (`RouteIndex`) rather than "Not found". Already on a router? Feed `ROUTES` to it and skip `GroveRoutes` — `matchRoute` and `resolveRoute` are exported for that.
+
+Multilingual documents compile each screen with a `MESSAGES` catalogue and `const t = useMessages(MESSAGES, "en")`: the active locale is the shell's, so every screen switches together — pass `locale` to the generated `GroveRoutes` to drive it from your own switcher.
+
+### Sign-in is a gate around the app
+
+`SignIn` takes the SDK's `auth` object and renders its children once a session exists: email + password, an account-creation form (when `auth.register` exists), and the second-factor step when a login answers `mfaRequired`. Errors show the API's own message. Persisting the session across reloads is the app's job — hand the SDK an `onTokensChanged` and restore with `setTokens` on boot.
+
 ### Deletes always confirm
 
 The `delete` action lets you override the confirmation *wording*, never whether the prompt happens. That guarantee lives in the library, not in the calling screen.
 
 ## Components
 
-`Stack` · `Grid` · `Divider` · `Heading` · `Text` · `Button` · `DataTable` · `Detail` · `Form` · `RelationSelect`
+`Stack` · `Grid` · `Divider` · `Heading` · `Text` · `Button` · `Header` · `DataTable` · `Detail` · `Form` · `RelationSelect` · `MarkdownField` · `GroveRoutes` · `RouteIndex` · `SignIn`
 
-Plus `GroveUiProvider`, `useAction`, `useGroveUi`, `formatValue`, `resolveHref`.
+Plus `GroveUiProvider`, `useAction`, `useGroveUi`, `useMessages`, `detectLocale`, `formatValue`, `resolveHref`, `matchRoute`, `resolveRoute`.
 
 ## License
 

package/dist/MarkdownField.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The editor a `format: "markdown"` field gets in a Form: a formatting toolbar over a
+ * textarea, plus a rendered preview.
+ *
+ * Ported from the dashboard's own MarkdownEditor so a generated app gets the same editor the
+ * Studio shows — a preview that flattered the real thing would be the usual trap. The port
+ * drops the shadcn/lucide imports for plain elements and inline SVG: this package ships to a
+ * user's app and must not drag a component library or an icon dependency in with it.
+ *
+ * The renderer is a deliberately small subset (headings, bold/italic, code, lists, links,
+ * paragraphs) and ESCAPES HTML FIRST, which is what makes injecting it safe — the stored
+ * value is untrusted content from whoever filled the form in.
+ */
+/** Markdown → HTML for the preview pane. Input is escaped before any tag is produced. */
+export declare function renderMarkdown(src: string): string;
+export declare function MarkdownField({ value, onChange, }: {
+    value: string;
+    onChange: (next: string) => void;
+}): import("react").JSX.Element;

package/dist/SignIn.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The sign-in gate a generated app mounts around its routes.
+ *
+ * Lives in the package rather than in the scaffold so it keeps improving with `npm update`:
+ * a scaffold is written once into the user's repo and never touched again by the generator,
+ * which is the right contract for a screen the user edits and the wrong one for an auth form
+ * that will grow a password reset, OAuth buttons and better errors.
+ *
+ * It talks to the SDK's `auth` object and nothing else — no URL, no key — so signing in goes
+ * through the same endpoints, and the same rate limits, as a hand-written form would.
+ */
+import type { ReactNode } from 'react';
+import type { Doc } from './types';
+/**
+ * The slice of the SDK's `client.auth` the gate uses. `login` may resolve with
+ * `{ mfaRequired: true }`, in which case `verifyMfa` finishes the sign-in — mirrors the SDK.
+ */
+export interface AuthLike {
+    login(email: string, password: string): Promise<Doc>;
+    register?(email: string, password: string, name?: string): Promise<Doc>;
+    verifyMfa?(code: string): Promise<Doc>;
+    /** Non-null when a session exists. The SDK keeps this in memory; persisting it is the app's job. */
+    getTokens(): {
+        accessToken: string;
+    } | null;
+}
+export interface SignInProps {
+    auth: AuthLike;
+    /** Shown above the form. Defaults to "Sign in". */
+    title?: ReactNode | undefined;
+    /** Offer an account-creation form. On by default when `auth.register` exists. */
+    allowRegister?: boolean | undefined;
+    /** Called with the user after a successful sign-in or registration. */
+    onSignedIn?: ((user: Doc) => void) | undefined;
+    /** What a signed-in viewer sees — normally the app's routes. */
+    children: ReactNode;
+}
+export declare function SignIn(props: SignInProps): import("react").JSX.Element;

package/dist/components.d.ts

@@ -7,7 +7,7 @@
  * could not reach by hand.
  */
 import type { ReactNode } from 'react';
-import type { ButtonVariant, CollectionLike, Doc, FieldRef, RowAction } from './types';
+import type { AnyCollection, ButtonVariant, CollectionLike, Doc, FieldRef, RowAction } from './types';
 import type { Action } from './types';
 declare const WIDTH: {
     full: string;
@@ -50,16 +50,38 @@ export declare function Text({ muted, children }: {
     muted?: boolean;
     children: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * Site header: brand, navigation, trailing actions.
+ *
+ * Navigation goes through the host's `navigate` (via `useAction`) rather than a bare `<a>`,
+ * so a header in a client-routed app does not full-page-reload on every link. The anchor's
+ * `href` is still real, which is what keeps middle-click, "open in new tab" and crawlers
+ * working — the click handler only takes over the plain-left-click case.
+ */
+export declare function Header(props: {
+    brand?: ReactNode;
+    brandHref?: string | undefined;
+    links?: ReadonlyArray<{
+        label: ReactNode;
+        href: string;
+    }> | undefined;
+    actions?: ReadonlyArray<{
+        label: ReactNode;
+        action: Action;
+        variant?: ButtonVariant | undefined;
+    }> | undefined;
+    sticky?: boolean | undefined;
+}): import("react").JSX.Element;
 export declare function Button(props: {
     action: Action;
     variant?: ButtonVariant | undefined;
     doc?: Doc | undefined;
-    collection?: CollectionLike | undefined;
+    collection?: AnyCollection | undefined;
     onDone?: (() => void) | undefined;
     children: ReactNode;
 }): import("react").JSX.Element;
 export declare function DataTable(props: {
-    collection: CollectionLike;
+    collection: AnyCollection;
     options?: {
         filter?: Record<string, unknown>;
         limit?: number;
@@ -73,13 +95,13 @@ export declare function DataTable(props: {
     resolveRelation?: (field: string) => CollectionLike;
 }): import("react").JSX.Element;
 export declare function Detail(props: {
-    collection: CollectionLike;
+    collection: AnyCollection;
     id: string;
     fields: FieldRef[];
     resolveRelation?: (field: string) => CollectionLike;
 }): import("react").JSX.Element;
 export declare function Form(props: {
-    collection: CollectionLike;
+    collection: AnyCollection;
     mode: 'create' | 'update';
     id?: string;
     fields: FieldRef[];

package/dist/index.d.ts

@@ -10,10 +10,15 @@
  * convention — this package is browser React bundled by `bun build`, not backend ESM, so the
  * convention buys nothing and extensionless is what every bundler agrees on.
  */
-import { Button, DataTable, Detail, Divider, Form, Grid, Heading, Stack, Text } from './components';
+import { Button, DataTable, Detail, Divider, Form, Grid, Header, Heading, Stack, Text } from './components';
+import { MarkdownField, renderMarkdown } from './MarkdownField';
 import { RelationSelect } from './RelationSelect';
-import { GroveUiProvider, formatValue, resolveHref, useAction, useGroveUi } from './runtime';
-export { Button, DataTable, Detail, Divider, Form, Grid, GroveUiProvider, Heading, RelationSelect, Stack, Text, formatValue, resolveHref, useAction, useGroveUi, };
+import { GroveRoutes, RouteIndex, matchRoute, resolveRoute } from './routes';
+import { SignIn } from './SignIn';
+import { GroveUiProvider, detectLocale, formatValue, resolveHref, useAction, useGroveUi, useMessages } from './runtime';
+export { Button, DataTable, Detail, Divider, Form, Grid, GroveRoutes, GroveUiProvider, Header, Heading, MarkdownField, renderMarkdown, RelationSelect, RouteIndex, SignIn, Stack, Text, detectLocale, formatValue, matchRoute, resolveHref, resolveRoute, useAction, useGroveUi, useMessages, };
 export type { RelationSelectProps } from './RelationSelect';
 export type { GroveUiContext } from './runtime';
-export type { Action, ButtonVariant, CollectionLike, Doc, FieldRef, Format, RowAction } from './types';
+export type { GroveRoute } from './routes';
+export type { AuthLike, SignInProps } from './SignIn';
+export type { Action, AnyCollection, ButtonVariant, CollectionLike, Doc, FieldRef, Format, RowAction } from './types';