@groveback/ui 0.1.1 → 0.3.0

package/dist/routes.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The routing shell a generated app runs its screens in.
+ *
+ * `grove gen --ui` emits `routes.tsx` as DATA — the `ROUTES` table — and this module is the
+ * code that consumes it. The split is deliberate: the table is derived from the Studio
+ * document (routes, params, titles) and belongs to the user's repo, while the matcher and the
+ * History wiring are behaviour that should improve with `npm update`, not sit frozen in every
+ * app that was scaffolded before a fix.
+ *
+ * Nothing here depends on a router library. `ROUTES` is the useful part; an app that already
+ * uses React Router or TanStack feeds the table to that and never mounts `GroveRoutes`.
+ */
+import type { ReactNode } from 'react';
+import type { GroveUiContext } from './runtime';
+export interface GroveRoute {
+    /** Route pattern, `:param` segments included. */
+    path: string;
+    /** Title authored in the Studio, when the screen has one. */
+    title?: string | undefined;
+    /**
+     * Whether a visitor must be signed in to see this route (D81). Absent means REQUIRED, so a
+     * route table written before this existed keeps behaving as it did.
+     */
+    requiresAuth?: boolean | undefined;
+    render: (params: Record<string, string>) => ReactNode;
+}
+/**
+ * Match a concrete path against a route pattern, capturing its params.
+ *
+ * Segment-wise, the same rule the Studio's validator and its preview use. Query and hash are
+ * ignored, a trailing slash is tolerated, and the root path is a real route: `/` must split to
+ * the same segments as the pattern `/`, which a bare "strip trailing slashes" would break by
+ * reducing it to an empty string.
+ */
+export declare function matchRoute(path: string, pattern: string): Record<string, string> | null;
+/**
+ * The route a path opens, and the params it carries.
+ *
+ * Specific routes win over parameterised ones regardless of the order given: `/articles/new`
+ * is a real page, and `/articles/:id` would otherwise swallow it by reading "new" as an id.
+ * Generic over the route shape so the Studio preview can resolve against its screens with the
+ * same rule the generated app uses.
+ */
+export declare function resolveRoute<T extends {
+    path: string;
+}>(routes: readonly T[], path: string): {
+    route: T;
+    params: Record<string, string>;
+} | null;
+/** The screen the current URL shows, under the provider the primitives dispatch through. */
+export declare function GroveRoutes(props: {
+    routes: readonly GroveRoute[];
+    /**
+     * Everything the primitives need beyond navigation — `endpointBase`, `locale`, `currency`,
+     * `confirm`. Navigation itself is owned here, since it must update the matched route.
+     */
+    context?: Omit<GroveUiContext, 'navigate'> | undefined;
+    /**
+     * Rendered when no route matches. Default: at `/` with no home screen, an index of the
+     * document's pages (a generated app should never open on "Not found"); anywhere else, a
+     * plain "Not found" with a way home.
+     */
+    fallback?: ReactNode | undefined;
+    /**
+     * Rendered inside the provider, ahead of the screen — where an app puts its own chrome.
+     * A gate that covers EVERY route goes outside instead (`<SignIn><GroveRoutes …/></SignIn>`).
+     */
+    children?: ReactNode | undefined;
+    /**
+     * Rendered in place of a route whose `requiresAuth` is not false while nobody is signed in
+     * (D81) — the generated app passes its `<SignIn>`. Per route rather than around the whole
+     * router, so one app can serve a public landing page and a private dashboard.
+     *
+     * Absent means no gate at all: a route table with no public/private distinction renders as
+     * it always did, and an app that wraps the router keeps working unchanged.
+     */
+    gate?: ((screen: ReactNode) => ReactNode) | undefined;
+}): import("react").JSX.Element;
+/**
+ * The pages of the document, for a root with no screen of its own. Only routes with no
+ * parameters are listed — `/books/:id` cannot be opened without a book.
+ */
+export declare function RouteIndex({ routes }: {
+    routes: readonly GroveRoute[];
+}): import("react").JSX.Element;

package/dist/runtime.d.ts

@@ -9,7 +9,13 @@ import type { Action, CollectionLike, Doc, Format } from './types';
 export interface GroveUiContext {
     /** Navigate to a route. */
     navigate: (href: string) => void;
-    /** Base URL for custom endpoint (`/run/*`) actions. */
+    /**
+     * Calls one of the project's custom endpoints WITH the app's session — `grove.client.run`
+     * in a generated app. Preferred over `endpointBase`, which is a bare `fetch` that carries
+     * no token and so runs the endpoint as nobody.
+     */
+    callEndpoint?: (path: string, method: 'POST' | 'GET') => Promise<unknown>;
+    /** Base URL for custom endpoint (`/run/*`) actions when no `callEndpoint` is given. */
     endpointBase?: string;
     /** Confirmation gate for destructive actions; defaults to window.confirm. */
     confirm?: (message: string) => boolean | Promise<boolean>;
@@ -43,8 +49,20 @@ export interface DispatchOptions {
  * left to whoever authored the screen.
  */
 export declare function useAction(): (action: Action, opts?: DispatchOptions) => Promise<void>;
-/** Render a stored value for display. Never throws — a bad value shows as empty. */
 export declare function formatValue(value: unknown, format: Format | undefined, opts?: {
     locale?: string | undefined;
     currency?: string | undefined;
 }): string;
+/**
+ * A translation lookup over the catalogue a multilingual screen carries, reading the active
+ * locale from the provider. The screen keeps its MESSAGES; the locale lives in ONE place —
+ * the routing shell's context — instead of a module variable per screen that nothing could
+ * set for all of them at once.
+ */
+export declare function useMessages(messages: Record<string, Record<string, string>>, fallback: string): (key: string) => string;
+/**
+ * The locale to start in: the first of the viewer's preferred languages the document has,
+ * matched exactly and then by language (`es-MX` finds `es`), else the document's first —
+ * its default — locale.
+ */
+export declare function detectLocale(locales: readonly string[], preferred?: readonly string[]): string;

package/dist/styles.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The class strings the primitives share, in one place so no two components can drift apart
+ * on the same control. Internal: nothing here is exported from the package.
+ *
+ * Both halves of every pair are declared. A control that paints a background must also paint
+ * its foreground, and it must state the LIGHT case rather than leaving it to inherit: a bare
+ * `dark:bg-neutral-950` fires on a viewer whose OS is in dark mode even when the surrounding
+ * page is light, which left a black input holding black text — invisible — on a white page.
+ */
+import type { ButtonVariant } from './types';
+export declare function cx(...parts: Array<string | false | undefined>): string;
+/** The one input skin, shared by text/number/date inputs and the enum select. */
+export declare const INPUT_CLASS: string;
+export declare const BUTTON_BASE: string;
+export declare const VARIANT: Record<ButtonVariant, string>;
+export declare const TONE: {
+    readonly error: "text-sm text-red-600";
+    readonly success: "text-sm text-green-700 dark:text-green-500";
+    readonly muted: "text-sm text-neutral-500";
+};

package/dist/types.d.ts

@@ -5,22 +5,54 @@
  */
 /** Minimal shape of a document as the SDK returns it. */
 export type Doc = Record<string, unknown>;
-/** The slice of the SDK's collection surface the primitives use. */
-export interface CollectionLike {
+/**
+ * The slice of the SDK's collection surface the primitives use.
+ *
+ * Generic in the document type so a `grove gen` TYPED collection is assignable. It cannot be
+ * `Doc` alone: a generated `interface Customers` has no index signature, and TypeScript does
+ * not give interfaces one implicitly, so `TypedCollection<Customers, …>` failed to satisfy
+ * `Promise<Doc[]>` — every screen `grove gen --ui` writes was a type error in the user's app.
+ *
+ * `TInput` is separate for the same reason on the write side: a generated `CustomersInput`
+ * has REQUIRED fields, so a `create(doc: Doc)` signature is not one it can satisfy. Both
+ * parameters default to `Doc`, which is what an untyped collection and the preview pass.
+ */
+export interface CollectionLike<TDoc extends Doc = Doc, TInput = Doc> {
     find(opts?: {
         filter?: Record<string, unknown>;
         limit?: number;
         skip?: number;
-    }): Promise<Doc[]>;
-    get(id: string): Promise<Doc>;
-    create(doc: Doc): Promise<Doc>;
-    update(id: string, patch: Doc): Promise<void>;
+    }): Promise<TDoc[]>;
+    get(id: string): Promise<TDoc>;
+    create(doc: TInput): Promise<TDoc>;
+    update(id: string, patch: Partial<TInput> & Doc): Promise<void>;
     delete(id: string): Promise<void>;
 }
-export type Format = 'text' | 'number' | 'currency' | 'date' | 'boolean';
+/**
+ * A collection of ANY document/input shape — what the primitives' props accept.
+ *
+ * The props cannot say `CollectionLike` (that is `CollectionLike<Doc, Doc>`, which a typed
+ * `TypedCollection<Customers, CustomersInput>` does not satisfy: `create` would have to take
+ * a loose `Doc` where the generated input has required fields). Making every component
+ * generic would push those parameters into four public prop types for no gain, since a
+ * primitive never uses the row type — it reads fields by a name that came from the IR.
+ *
+ * So the props are deliberately shape-agnostic here, and the type safety lives where it is
+ * useful: in the caller's own code, where `grove.collections.customers` is still fully typed.
+ *
+ * `any` for the input is what makes BOTH directions work — a Form assembles a plain object
+ * and passes it to `create`, while a generated collection demands its own required fields.
+ * It is confined to this one alias and never reaches a caller's types.
+ */
+export type AnyCollection = CollectionLike<Doc, any>;
+export type Format = 'text' | 'markdown' | 'number' | 'currency' | 'date' | 'boolean';
 export interface FieldRef {
     field: string;
     label: string;
+    /** Allowed values (the schema's `enum`). A form renders these as a select. */
+    options?: string[] | undefined;
+    /** Column width in a table: `narrow` | `normal` | `wide`. Ignored outside a DataTable. */
+    width?: 'narrow' | 'normal' | 'wide' | undefined;
     format?: Format;
     /** For an x-ref field: show this field of the referenced document instead of the id. */
     display?: {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@groveback/ui",
-  "version": "0.1.1",
-  "description": "React primitives for Groveback Studio screens \u2014 tables, forms, detail views and relation pickers that read through the Groveback SDK, so every query passes the policy engine.",
+  "version": "0.3.0",
+  "description": "React primitives for Groveback Studio screens — tables, forms, detail views and relation pickers that read through the Groveback SDK, so every query passes the policy engine.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -10,15 +10,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
-    }
+    },
+    "./tailwind.css": "./tailwind.css"
   },
   "files": [
-    "dist"
+    "dist",
+    "tailwind.css"
   ],
-  "//sideEffects": "NOT set to false: bun 1.4's bundler treats it as licence to drop the entire entry point, emitting the export names with nothing behind them \u2014 a 193-byte module exporting symbols that do not exist, reported as a successful build. The check-bundle script guards against a regression.",
+  "//sideEffects": "NOT set to false: bun 1.4's bundler treats it as licence to drop the entire entry point, emitting the export names with nothing behind them — a 193-byte module exporting symbols that do not exist, reported as a successful build. The check-bundle script guards against a regression.",
   "scripts": {
     "build": "rm -rf dist && bun build ./src/index.ts --outdir dist --target browser --format esm --external react --external react-dom && bun run check-bundle && bunx tsc -p tsconfig.json && cp ../../LICENSE .",
-    "check-bundle": "bun -e \"const s=(await Bun.file('dist/index.js').text()); if(!s.includes('DataTable')||s.length<5000){console.error('dist/index.js looks empty ('+s.length+' bytes) \u2014 the bundler dropped modules');process.exit(1)}\""
+    "check-bundle": "bun -e \"const s=(await Bun.file('dist/index.js').text()); if(!s.includes('DataTable')||s.length<5000){console.error('dist/index.js looks empty ('+s.length+' bytes) — the bundler dropped modules');process.exit(1)}\""
   },
   "peerDependencies": {
     "react": ">=18",

package/tailwind.css

@@ -0,0 +1,12 @@
+/*
+ * Tell Tailwind where @groveback/ui's classes live.
+ *
+ * The primitives are styled with Tailwind utilities but ship no CSS of their own, so the
+ * app's Tailwind build has to scan this package or every class goes unemitted and the
+ * screens render unstyled. `@source` here is relative to THIS file, so importing it works
+ * from any install layout (hoisted, pnpm, a workspace link) without the app guessing a
+ * node_modules path. In your app's CSS, after `@import "tailwindcss";`:
+ *
+ *   @import "@groveback/ui/tailwind.css";
+ */
+@source "./dist/index.js";