@hanzo/ui 8.0.22 → 8.0.24

package/dist/framework/CollectionsBrowser.d.ts

@@ -0,0 +1,44 @@
+/**
+ * CollectionsBrowser — the app-lane home: the DocTypes of a `module` (a CMS
+ * "collection" IS a framework DocType tagged with the lane's module). It lists
+ * them as cards, offers a first-run "Set up" that installs the lane's fixtures
+ * (POST /v1/framework/modules/:module/install), and a "New collection" that opens
+ * the dynamic content-type builder (name + typed fields, on-page). Everything is
+ * per-org and honest — an org with the lane not yet installed sees the setup CTA,
+ * never a fabricated collection.
+ *
+ * This is generic over `module`, so CMS (`cms`), ERP (`erp`), and Helpdesk
+ * (`help`) all reuse it — the ONE collections home for every lane.
+ */
+import { type ReactNode } from 'react';
+import type { FrameworkClient } from './client';
+export interface CollectionsBrowserProps {
+    client: FrameworkClient;
+    /** The app lane: 'cms' | 'erp' | 'help' | … */
+    module: string;
+    /** Human label for the lane (e.g. "Content"). */
+    label: string;
+    subtitle: string;
+    /** Open a collection's records. */
+    onOpen: (doctype: string) => void;
+    /**
+     * Lane-appropriate copy for the first-run (pre-install) empty state. Optional and
+     * defaulted to the CMS wording, so this component stays generic over the lane: a
+     * CMS caller renders identically, while ERP/Help pass their own description +
+     * bullets. Additive only — no behavior/permission/proxy change.
+     */
+    setupDescription?: string;
+    setupBullets?: string[];
+    /**
+     * Schema AUTHORING is a separate concern from schema USE, so it is injected
+     * rather than imported: a host that can define collections (the console's
+     * CollectionBuilder) supplies this; a host that only consumes them (a site
+     * shell) omits it and the "New collection" affordance is simply not offered.
+     * Nothing is faked either way.
+     */
+    renderBuilder?: (p: {
+        onSaved: (doctype: string) => void;
+        onCancel: () => void;
+    }) => ReactNode;
+}
+export declare function CollectionsBrowser({ client, module, label, subtitle, onOpen, setupDescription, setupBullets, renderBuilder }: CollectionsBrowserProps): import("react/jsx-runtime").JSX.Element;

package/dist/framework/DocTypeDetail.d.ts

@@ -0,0 +1,13 @@
+import type { FrameworkClient } from './client';
+export interface DocTypeDetailProps {
+    client: FrameworkClient;
+    doctype: string;
+    /** Document name, or `'new'` to open the create form. */
+    name: string;
+    /** Active project scope — stamped onto a NEW record when the collection has a `project` field. */
+    project?: string;
+    onBack: () => void;
+    /** Land on a document (after create). */
+    onView: (name: string) => void;
+}
+export declare function DocTypeDetail({ client, doctype, name, project, onBack, onView }: DocTypeDetailProps): import("react/jsx-runtime").JSX.Element;

package/dist/framework/DocTypeRecords.d.ts

@@ -0,0 +1,43 @@
+/**
+ * DocTypeRecords — the Twenty-grade records surface for ONE framework DocType,
+ * driven ENTIRELY by DocType metadata. It loads the schema (→ @hanzo/data
+ * `FieldDefinition[]` via `docTypeToFields`), the documents, and each relation's
+ * candidate records, then renders through @hanzo/data's `RecordsView` — the shared
+ * table ⇆ board view with filter/sort/group, inline cell editing, and a detail
+ * hand-off. Every field type shows the right Display/Input with ZERO per-doctype
+ * code, so a CMS Page, an ERP Invoice, or a Helpdesk Ticket all render here.
+ *
+ * Persistence is REAL: an inline cell edit sends the FULL record (the engine
+ * validates the whole document on update) via `savePayload`, and reflects the
+ * server's row. States are honest — loading / empty / backend-error, never a
+ * fabricated row.
+ */
+import { type ReactNode } from 'react';
+import type { FrameworkClient } from './client';
+import type { DocType, FrameworkDoc } from './types';
+export interface DocTypeRecordsProps {
+    client: FrameworkClient;
+    /** DocType name to render. */
+    doctype: string;
+    /** Open a document's detail (by document name). */
+    onOpen: (name: string) => void;
+    /** Start creating a document. */
+    onCreate: () => void;
+    /** Active project scope — filters the list when the collection has a `project` field. */
+    project?: string;
+    title?: ReactNode;
+    /**
+     * An asset library (a DocType whose required field is an Attach) is better
+     * shown as a gallery than a table, but uploading bytes needs the HOST's object
+     * store — not something this layer can know. So the gallery is injected: a host
+     * with a DAM supplies it, a host without one gets the honest generic table.
+     */
+    renderMedia?: (p: {
+        dt: DocType;
+        docs: FrameworkDoc[];
+        onOpen: (name: string) => void;
+        onChanged: () => void;
+        toolbarExtra: ReactNode;
+    }) => ReactNode;
+}
+export declare function DocTypeRecords({ client, doctype, onOpen, onCreate, project, title, renderMedia }: DocTypeRecordsProps): import("react/jsx-runtime").JSX.Element;

package/dist/framework/Loader.d.ts

@@ -0,0 +1,4 @@
+export declare function Loader({ label, size }: {
+    label?: string;
+    size?: number;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/framework/client.d.ts

@@ -0,0 +1,87 @@
+/**
+ * FrameworkApi — the ONE generic client for the Hanzo Framework DocType engine
+ * (cloud `clients/framework`, live at /v1/framework/*). It is metadata-driven and
+ * doctype-agnostic: the SAME `records` CRUD serves a CMS Page, an ERP Invoice, or
+ * a Helpdesk Ticket — an app lane is just a `module` filter over `doctypes`.
+ *
+ * TRANSPORT IS INJECTED. This layer knows the framework's *shape*, never how a
+ * given host reaches it: the console proxies through its own user-bearer BFF, the
+ * site shells (erp/crm/cms/help.<brand>) call the API origin with the IAM bearer
+ * directly. Both hand a `Transport` to `createFrameworkClient` and get the SAME
+ * client, so there is exactly one definition of the wire surface.
+ *
+ * Names (DocType + document) are used verbatim in the URL path, so a host keeps
+ * them slug-style (no spaces/`%`) and this encodes each segment. Payloads are read
+ * defensively from `{ data }` (or a bare array), so a shape drift degrades a list
+ * rather than throwing.
+ */
+import type { DocType, FrameworkDoc, ListQuery, ModuleInfo, InstallResult } from './types';
+/**
+ * The four verbs the framework surface needs, relative to the caller's
+ * `/v1/framework` root. A host implements this over whatever credential path it
+ * already owns — this layer never touches auth, cookies, or origins.
+ */
+export interface Transport {
+    get: <T>(path: string) => Promise<T>;
+    post: <T>(path: string, body?: unknown) => Promise<T>;
+    put: <T>(path: string, body?: unknown) => Promise<T>;
+    del: (path: string) => Promise<void>;
+}
+/** Build the generic document list querystring from a typed ListQuery. */
+export declare function listQuery(q?: ListQuery): string;
+/** Build the framework client over a host's transport. */
+export declare function createFrameworkClient(t: Transport): {
+    /** The DocType registry (schemas) — the collection definitions of every app lane. */
+    doctypes: {
+        list: () => Promise<DocType[]>;
+        get: (name: string) => Promise<DocType>;
+        create: (dt: DocType) => Promise<DocType>;
+        update: (name: string, dt: DocType) => Promise<DocType>;
+        remove: (name: string) => Promise<void>;
+    };
+    /** Generic, metadata-driven document CRUD — the SAME calls for ANY doctype. */
+    records: {
+        list: (doctype: string, q?: ListQuery) => Promise<FrameworkDoc[]>;
+        get: (doctype: string, name: string) => Promise<FrameworkDoc>;
+        create: (doctype: string, data: Record<string, unknown>) => Promise<FrameworkDoc>;
+        update: (doctype: string, name: string, data: Record<string, unknown>) => Promise<FrameworkDoc>;
+        remove: (doctype: string, name: string) => Promise<void>;
+        submit: (doctype: string, name: string) => Promise<FrameworkDoc>;
+        cancel: (doctype: string, name: string) => Promise<FrameworkDoc>;
+    };
+    /** App-lane fixtures: list the registered lanes, inspect one, install into the org. */
+    modules: {
+        list: () => Promise<ModuleInfo[]>;
+        get: (module: string) => Promise<ModuleInfo>;
+        install: (module: string) => Promise<InstallResult>;
+    };
+    /** Per-org role assignments (grant editors; the owner is seeded System Manager). */
+    roles: {
+        list: () => Promise<{
+            user: string;
+            role: string;
+        }[]>;
+        assign: (user: string, role: string) => Promise<void>;
+        revoke: (user: string, role: string) => Promise<void>;
+    };
+};
+export type FrameworkClient = ReturnType<typeof createFrameworkClient>;
+/** An HTTP failure carrying the status, so `classifyBackend` can tell 401 from 403 from 404. */
+export declare class FrameworkHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface FetchTransportOptions {
+    /** Absolute `/v1/framework` root, e.g. `https://api.hanzo.ai/v1/framework`. */
+    baseUrl: string;
+    /** Called per request — a bearer token, or null when signed out. */
+    token?: () => string | null | undefined;
+    /** Injectable for tests; defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * The bearer transport every site shell uses: the caller's IAM access token on
+ * the Authorization header, straight to the API origin. No cookie, no second
+ * credential path — the engine resolves the org from the token's owner claim.
+ */
+export declare function fetchTransport(opts: FetchTransportOptions): Transport;

package/dist/framework/data.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared, non-React data helpers for the generic DocType renderer. A relation
+ * (Link) field is a picker over the TARGET doctype's records, so before a view
+ * can render or edit one it must load those records (+ the target's schema for
+ * the human label). This is the ONE place that does it, used by both the records
+ * list and the record detail — no per-view duplication.
+ */
+import type { SelectOption, FieldDefinition } from '@hanzo/data';
+import type { DocType } from './types';
+import type { FrameworkClient } from './client';
+/** The picker options for every Link field of `dt`: value = target id, label = its title. */
+export declare function loadLinkOptions(client: FrameworkClient, dt: DocType): Promise<Record<string, SelectOption[]>>;
+/**
+ * The `fieldOptions` callback @hanzo/data's views take: relation fields get their
+ * loaded target records; select fields get the choices declared in metadata (so
+ * the table cell and the form input agree). Everything else → undefined.
+ */
+export declare function makeFieldOptions(linkOptions: Record<string, SelectOption[]>): (field: FieldDefinition) => SelectOption[] | undefined;

package/dist/framework/fields.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure mapping between the Hanzo Framework DocType metadata and @hanzo/data's
+ * render model — the brain of the generic DocType renderer. It is the ONE place
+ * that translates the engine's Frappe field vocabulary into @hanzo/data's, so
+ * EVERY app lane (CMS/ERP/CRM/Helpdesk) renders list/form/detail identically with
+ * zero per-doctype code. A new DocType — or a whole new lane — "just works".
+ *
+ * No I/O, no React — data in, data out, trivially testable (the @hanzo/data
+ * imports are `import type`, erased at build, so the unit test runs in plain Node).
+ */
+import type { FieldDefinition, SelectOption } from '@hanzo/data';
+import type { DocField, DocType, FrameworkDoc } from './types';
+/** `first_name` / `firstName` → "First Name"; known acronyms upper-cased. */
+export declare function humanize(name: string): string;
+/** The autoname source field for a `field:xxx` rule (`""` otherwise). */
+export declare function autonameSource(dt: DocType): string;
+export interface FieldMapOpts {
+    /** Editing an existing record: the autoname-source field is fixed (the URL key). */
+    editing?: boolean;
+}
+/**
+ * Map a DocType's fields to the ordered `FieldDefinition[]` every @hanzo/data view
+ * renders from. Hidden fields are dropped; the engine's readOnly is honored; and
+ * when editing an existing record the autoname source (e.g. `slug`) is made
+ * read-only because it IS the document's immutable URL key.
+ */
+export declare function docTypeToFields(dt: DocType, opts?: FieldMapOpts): FieldDefinition[];
+/** The status field a publishable content type uses (a Select including "Published"). */
+export declare function statusField(dt: DocType): string;
+/** Fields shown as table columns: the `inListView` subset (all, if none flagged). */
+export declare function listHiddenFields(dt: DocType): string[];
+/** True when a DocType is a media/asset library (a required Attach) → grid view. */
+export declare function isMediaDoctype(dt: DocType): boolean;
+/** The primary Attach field name (the asset URL) of a media doctype. */
+export declare function mediaFileField(dt: DocType): string;
+/** DocTypes belonging to an app lane (module) — a CMS "collection" is one of these. */
+export declare function moduleDoctypes(dts: DocType[], module: string): DocType[];
+/** The conventional field a collection uses to scope documents to a project. */
+export declare const PROJECT_FIELD = "project";
+/** True when a DocType declares the `project` scope field (→ project filtering works). */
+export declare function hasProjectField(dt: DocType): boolean;
+/** A record's human title — the DocType's titleField, else its name. */
+export declare function titleOf(doc: Record<string, unknown>, dt: DocType): string;
+/**
+ * URL-safe slug from arbitrary text: lower-case, any run of non-alphanumerics
+ * collapsed to a single dash, ends trimmed. Guarantees a no-space, `%`-free
+ * document name (the engine and the console's own proxy path both require it).
+ */
+export declare function slugify(s: unknown): string;
+/** Valid Pascal/slug DocType name (letters/digits/dash/underscore, alnum-led, no space). */
+export declare function isValidDoctypeName(name: string): boolean;
+/**
+ * A framework document → a flat @hanzo/data record: the field values coerced to
+ * their display shapes, plus `id` (the record key every view uses) and the managed
+ * envelope. The ONE read mapping every DocType view shares.
+ */
+export declare function toRecord(doc: FrameworkDoc, dt: DocType): Record<string, unknown>;
+/**
+ * Enrich a record's Link values with the target's human label ({id,label}), so a
+ * relation renders as its title (not a raw id) in BOTH the list cell and the
+ * detail — @hanzo/data's relation display reads `.label`, its input reads `.id`.
+ * `optionsByField` is the loaded picker options per Link field (value=id, label=title).
+ */
+export declare function enrichLinks(record: Record<string, unknown>, dt: DocType, optionsByField: Record<string, SelectOption[]>): Record<string, unknown>;
+/** The Link fields of a DocType (their options must be loaded for the picker). */
+export declare function linkFields(dt: DocType): DocField[];
+/** A blank create-form draft seeded with each field's declared default (Check → bool). */
+export declare function newDraft(dt: DocType): Record<string, unknown>;
+/**
+ * A draft record → the framework write body: editable field values only (the
+ * engine owns `name`/`docstatus`/timestamps), each coerced to its wire shape, and
+ * the autoname source (e.g. `slug`) slugified so the document name is always URL-
+ * safe. Fields left `undefined` are dropped — a partial edit never nulls a value.
+ */
+export declare function savePayload(draft: Record<string, unknown>, dt: DocType): Record<string, unknown>;

package/dist/framework/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `@hanzo/ui/framework` — the generic renderer for the Hanzo Framework DocType
+ * engine (cloud `clients/framework`, /v1/framework/*).
+ *
+ * The engine's thesis is that a business app IS a set of DocTypes: an ERP Sales
+ * Order, a CRM Deal, a CMS Page and a Helpdesk Ticket differ only in metadata.
+ * This module is the other half of that thesis — ONE list, ONE detail, ONE form,
+ * driven entirely by that metadata, so every lane renders with zero per-app UI.
+ *
+ * Three seams keep it host-agnostic:
+ *   • `Transport` — how a host reaches /v1/framework (BFF proxy vs IAM bearer).
+ *   • `renderBuilder` — schema AUTHORING, which only an admin surface offers.
+ *   • `renderMedia` — an asset gallery, which needs the host's object store.
+ * Anything a host does not supply is simply not offered; nothing is faked.
+ */
+export * from './types';
+export * from './fields';
+export * from './client';
+export * from './data';
+export { Loader } from './Loader';
+export { CollectionsBrowser, type CollectionsBrowserProps } from './CollectionsBrowser';
+export { DocTypeRecords, type DocTypeRecordsProps } from './DocTypeRecords';
+export { DocTypeDetail, type DocTypeDetailProps } from './DocTypeDetail';

package/dist/framework/types.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The Hanzo Framework wire types — the DocType/DocField/document contract the
+ * cloud `clients/framework` engine serves at /v1/framework/* (Frappe's DocType
+ * metadata core, rebuilt native in Go). These mirror the Go JSON tags exactly.
+ *
+ * This is the ONE metadata vocabulary the generic @hanzo/data DocType renderer
+ * builds from, so CMS/ERP/CRM/Helpdesk — all "just DocTypes" on the engine —
+ * render through the SAME components. Types only; no runtime.
+ */
+/** The engine's closed fieldtype set (mirrors clients/framework/doctype.go). */
+export type Fieldtype = 'Data' | 'Int' | 'Float' | 'Currency' | 'Check' | 'Date' | 'Datetime' | 'Text' | 'SmallText' | 'LongText' | 'RichText' | 'Select' | 'Link' | 'Table' | 'Attach' | 'JSON' | 'Password';
+/** One field of a DocType (Frappe's DocField). */
+export interface DocField {
+    fieldname: string;
+    fieldtype: Fieldtype;
+    label?: string;
+    reqd?: boolean;
+    /** Select → newline-separated choices; Link → target DocType; Table → child DocType. */
+    options?: string;
+    default?: string;
+    unique?: boolean;
+    readOnly?: boolean;
+    hidden?: boolean;
+    inListView?: boolean;
+    fetchFrom?: string;
+}
+/** A role's rights on a DocType (Frappe's DocPerm). */
+export interface DocPerm {
+    role: string;
+    read?: boolean;
+    write?: boolean;
+    create?: boolean;
+    delete?: boolean;
+    submit?: boolean;
+    cancel?: boolean;
+}
+/** A DocType definition — per-org metadata. */
+export interface DocType {
+    name: string;
+    module?: string;
+    isSingle?: boolean;
+    isSubmittable?: boolean;
+    autoname?: string;
+    titleField?: string;
+    fields: DocField[];
+    permissions?: DocPerm[];
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** The managed document envelope keys the engine always returns. */
+export interface DocEnvelope {
+    name: string;
+    doctype: string;
+    /** 0 = draft, 1 = submitted, 2 = cancelled. */
+    docstatus: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** A document: the field data overlaid with the managed envelope keys. */
+export type FrameworkDoc = Record<string, unknown> & DocEnvelope;
+/** A registered app lane and (optionally, per-org) which fixtures are installed. */
+export interface ModuleInfo {
+    module: string;
+    doctypes: string[];
+    installed?: string[];
+}
+/** The result of installing a module into the caller's org. */
+export interface InstallResult {
+    module: string;
+    created: string[];
+    existing: string[];
+}
+/** List query for the generic document surface. */
+export interface ListQuery {
+    filters?: Record<string, string | number | boolean>;
+    fields?: string[];
+    orderBy?: string;
+    limit?: number;
+}
+/** The redacted-Password marker the engine returns for a set secret. */
+export declare const REDACTED_MARKER = "__set__";