@realiizlabs/admin 0.8.0 → 0.8.1

package/dist/forms-ui/index.d.cts

@@ -1,7 +1,78 @@
 import * as react from 'react';
-import { C as ContentTypeEntry } from '../types-DsSMscTh.cjs';
+import { ReactNode } from 'react';
+import { C as ContentTypeEntry } from '../types-DyryuIX1.cjs';
 import 'zod';
 
+/**
+ * Control strings ↔ frontmatter values. Pure.
+ *
+ * Controls hold strings (or booleans / Files). The schema wants typed values.
+ * `toControl` seeds a control from an existing frontmatter value — including
+ * a Date from a previously-parsed file — and `toValue` assembles what goes to
+ * safeParse. Anything the schema then coerces (dates) is the schema's business.
+ */
+
+/** Stand-in path for an image chosen but not yet uploaded — replaced by ADMIN-06. */
+declare const PENDING_UPLOAD_PREFIX = "pending-upload/";
+
+type LabelRenderer = (label: string, help: string) => ReactNode;
+/**
+ * Advisory length gauge. The bar is the whole scale (a bit past the max so
+ * "over" has room to show), a green band marks the target range, and the fill
+ * grows with the text in the state's colour: grey while short, green in range,
+ * red past it. The words repeat only what the bar can't: the count and a verdict.
+ */
+declare function LengthGauge({ length: raw, range, suffix }: {
+    length: number;
+    range: [number, number];
+    suffix?: string;
+}): react.JSX.Element;
+
+/**
+ * Toolbar edits — pure functions (text, selStart, selEnd) → { text, a, b }.
+ *
+ * Every formatting tool TOGGLES, like the surveillance-review report editor:
+ * bold on bold text un-bolds; H2 on an H2 line removes it; H3 on an H2 line
+ * swaps it; link anywhere inside a link removes it. `activeTools` reports which
+ * of them the caret is currently "in", so the buttons can light up and say what
+ * they're about to do.
+ */
+type Edit = {
+    text: string;
+    a: number;
+    b: number;
+};
+type Apply = (s: string, a: number, b: number) => Edit;
+interface Tool {
+    id: string;
+    title: string;
+    apply: Apply;
+}
+declare const TOOLS: Tool[];
+
+interface MarkdownEditorProps {
+    id: string;
+    name?: string;
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+    /** Host-supplied renderer returning HTML. Errors should be returned as `{ error }`. */
+    renderPreview?: (markdown: string) => Promise<{
+        html: string;
+    } | {
+        error: string;
+    }>;
+    /** Extra class on the preview body, e.g. the site's own prose class so it matches the blog. */
+    previewClassName?: string;
+    minHeight?: number;
+    /**
+     * Name of the site's tooltip MDX component, e.g. "Term" → a toolbar button that wraps the
+     * selection as `<Term definition="">word</Term>`. Off unless the site has such a component.
+     */
+    termComponent?: string;
+}
+declare function MarkdownEditor({ id, name, value, onChange, placeholder, renderPreview, previewClassName, minHeight, termComponent }: MarkdownEditorProps): react.JSX.Element;
+
 interface ContentFormSubmission {
     frontmatter: Record<string, unknown>;
     body: string;
@@ -23,19 +94,59 @@ interface ContentFormProps {
      */
     showBody?: boolean;
     bodyLabel?: string;
+    /** Host-supplied Markdown/MDX renderer for the Preview tab. Without it the editor is edit-only. */
+    renderPreview?: MarkdownEditorProps["renderPreview"];
+    previewClassName?: string;
+    /** Site tooltip MDX component name (e.g. "Term") to expose as a toolbar button. */
+    termComponent?: string;
+    /**
+     * Put Cancel/Save in a bar that the host can pin to the bottom of the page
+     * (`.realiiz-form__bar`; the shell makes it sticky). The bar also reports
+     * "Unsaved changes" / "No changes yet", or `status` when the host supplies one.
+     */
+    stickyBar?: boolean;
+    status?: ReactNode;
+    /** Extra controls in the bar, before Cancel/Save — e.g. a link to review a pending change. */
+    barExtra?: ReactNode;
+    /** Rendered after the fields and before the bar — the right place for a quiet destructive action (remove this item). */
+    footer?: ReactNode;
+    /** Draw a field label that has `.meta({ help })` — pass the site's tooltip component so labels explain themselves. */
+    renderLabel?: LabelRenderer;
+    /**
+     * Fill `target` from `source` while the person types, until they edit `target`
+     * themselves — e.g. { source: "title", target: "slug" } for a web address.
+     * Only kicks in when `target` started empty (a new item), never on an existing one.
+     */
+    derive?: {
+        source: string;
+        target: string;
+        transform?: (value: string) => string;
+    };
+    /**
+     * Warn before leaving with unsaved edits: the browser's own prompt on close/reload,
+     * and a confirm on in-app link clicks (which never fire beforeunload). Default true.
+     */
+    guardUnsaved?: boolean;
 }
-declare function ContentForm({ entry, initialValues, initialBody, onSubmit, onCancel, submitLabel, className, showBody, bodyLabel }: ContentFormProps): react.JSX.Element;
+/** "Hello, World! 2026" → "hello-world-2026" — the same rule the blog's slug regex enforces. */
+declare function slugify(s: string): string;
+declare function ContentForm({ entry, initialValues, initialBody, onSubmit, onCancel, submitLabel, className, showBody, bodyLabel, renderPreview, previewClassName, termComponent, stickyBar, status, barExtra, footer, renderLabel, derive, guardUnsaved }: ContentFormProps): react.JSX.Element;
 
 /**
- * Control strings ↔ frontmatter values. Pure.
- *
- * Controls hold strings (or booleans / Files). The schema wants typed values.
- * `toControl` seeds a control from an existing frontmatter value — including
- * a Date from a previously-parsed file — and `toValue` assembles what goes to
- * safeParse. Anything the schema then coerces (dates) is the schema's business.
+ * ChipsInput — tags as chips. Enter or comma adds, × or Backspace-on-empty
+ * removes. The value is a string[]; the schema's length/regex rules still run
+ * on submit, this is only a nicer way to type them.
  */
+declare function ChipsInput({ id, name, value, onChange, onBlur, placeholder, invalid, max }: {
+    id: string;
+    name: string;
+    value: string[];
+    onChange: (v: string[]) => void;
+    onBlur: () => void;
+    placeholder?: string;
+    invalid?: boolean;
+    /** When the schema says exactly N, show "n of N". */
+    max?: number;
+}): react.JSX.Element;
 
-/** Stand-in path for an image chosen but not yet uploaded — replaced by ADMIN-06. */
-declare const PENDING_UPLOAD_PREFIX = "pending-upload/";
-
-export { ContentForm, type ContentFormProps, type ContentFormSubmission, PENDING_UPLOAD_PREFIX };
+export { ChipsInput, ContentForm, type ContentFormProps, type ContentFormSubmission, type LabelRenderer, LengthGauge, MarkdownEditor, type MarkdownEditorProps, PENDING_UPLOAD_PREFIX, TOOLS, slugify };

package/dist/forms-ui/index.d.ts

@@ -1,7 +1,78 @@
 import * as react from 'react';
-import { C as ContentTypeEntry } from '../types-DsSMscTh.js';
+import { ReactNode } from 'react';
+import { C as ContentTypeEntry } from '../types-DyryuIX1.js';
 import 'zod';
 
+/**
+ * Control strings ↔ frontmatter values. Pure.
+ *
+ * Controls hold strings (or booleans / Files). The schema wants typed values.
+ * `toControl` seeds a control from an existing frontmatter value — including
+ * a Date from a previously-parsed file — and `toValue` assembles what goes to
+ * safeParse. Anything the schema then coerces (dates) is the schema's business.
+ */
+
+/** Stand-in path for an image chosen but not yet uploaded — replaced by ADMIN-06. */
+declare const PENDING_UPLOAD_PREFIX = "pending-upload/";
+
+type LabelRenderer = (label: string, help: string) => ReactNode;
+/**
+ * Advisory length gauge. The bar is the whole scale (a bit past the max so
+ * "over" has room to show), a green band marks the target range, and the fill
+ * grows with the text in the state's colour: grey while short, green in range,
+ * red past it. The words repeat only what the bar can't: the count and a verdict.
+ */
+declare function LengthGauge({ length: raw, range, suffix }: {
+    length: number;
+    range: [number, number];
+    suffix?: string;
+}): react.JSX.Element;
+
+/**
+ * Toolbar edits — pure functions (text, selStart, selEnd) → { text, a, b }.
+ *
+ * Every formatting tool TOGGLES, like the surveillance-review report editor:
+ * bold on bold text un-bolds; H2 on an H2 line removes it; H3 on an H2 line
+ * swaps it; link anywhere inside a link removes it. `activeTools` reports which
+ * of them the caret is currently "in", so the buttons can light up and say what
+ * they're about to do.
+ */
+type Edit = {
+    text: string;
+    a: number;
+    b: number;
+};
+type Apply = (s: string, a: number, b: number) => Edit;
+interface Tool {
+    id: string;
+    title: string;
+    apply: Apply;
+}
+declare const TOOLS: Tool[];
+
+interface MarkdownEditorProps {
+    id: string;
+    name?: string;
+    value: string;
+    onChange: (v: string) => void;
+    placeholder?: string;
+    /** Host-supplied renderer returning HTML. Errors should be returned as `{ error }`. */
+    renderPreview?: (markdown: string) => Promise<{
+        html: string;
+    } | {
+        error: string;
+    }>;
+    /** Extra class on the preview body, e.g. the site's own prose class so it matches the blog. */
+    previewClassName?: string;
+    minHeight?: number;
+    /**
+     * Name of the site's tooltip MDX component, e.g. "Term" → a toolbar button that wraps the
+     * selection as `<Term definition="">word</Term>`. Off unless the site has such a component.
+     */
+    termComponent?: string;
+}
+declare function MarkdownEditor({ id, name, value, onChange, placeholder, renderPreview, previewClassName, minHeight, termComponent }: MarkdownEditorProps): react.JSX.Element;
+
 interface ContentFormSubmission {
     frontmatter: Record<string, unknown>;
     body: string;
@@ -23,19 +94,59 @@ interface ContentFormProps {
      */
     showBody?: boolean;
     bodyLabel?: string;
+    /** Host-supplied Markdown/MDX renderer for the Preview tab. Without it the editor is edit-only. */
+    renderPreview?: MarkdownEditorProps["renderPreview"];
+    previewClassName?: string;
+    /** Site tooltip MDX component name (e.g. "Term") to expose as a toolbar button. */
+    termComponent?: string;
+    /**
+     * Put Cancel/Save in a bar that the host can pin to the bottom of the page
+     * (`.realiiz-form__bar`; the shell makes it sticky). The bar also reports
+     * "Unsaved changes" / "No changes yet", or `status` when the host supplies one.
+     */
+    stickyBar?: boolean;
+    status?: ReactNode;
+    /** Extra controls in the bar, before Cancel/Save — e.g. a link to review a pending change. */
+    barExtra?: ReactNode;
+    /** Rendered after the fields and before the bar — the right place for a quiet destructive action (remove this item). */
+    footer?: ReactNode;
+    /** Draw a field label that has `.meta({ help })` — pass the site's tooltip component so labels explain themselves. */
+    renderLabel?: LabelRenderer;
+    /**
+     * Fill `target` from `source` while the person types, until they edit `target`
+     * themselves — e.g. { source: "title", target: "slug" } for a web address.
+     * Only kicks in when `target` started empty (a new item), never on an existing one.
+     */
+    derive?: {
+        source: string;
+        target: string;
+        transform?: (value: string) => string;
+    };
+    /**
+     * Warn before leaving with unsaved edits: the browser's own prompt on close/reload,
+     * and a confirm on in-app link clicks (which never fire beforeunload). Default true.
+     */
+    guardUnsaved?: boolean;
 }
-declare function ContentForm({ entry, initialValues, initialBody, onSubmit, onCancel, submitLabel, className, showBody, bodyLabel }: ContentFormProps): react.JSX.Element;
+/** "Hello, World! 2026" → "hello-world-2026" — the same rule the blog's slug regex enforces. */
+declare function slugify(s: string): string;
+declare function ContentForm({ entry, initialValues, initialBody, onSubmit, onCancel, submitLabel, className, showBody, bodyLabel, renderPreview, previewClassName, termComponent, stickyBar, status, barExtra, footer, renderLabel, derive, guardUnsaved }: ContentFormProps): react.JSX.Element;
 
 /**
- * Control strings ↔ frontmatter values. Pure.
- *
- * Controls hold strings (or booleans / Files). The schema wants typed values.
- * `toControl` seeds a control from an existing frontmatter value — including
- * a Date from a previously-parsed file — and `toValue` assembles what goes to
- * safeParse. Anything the schema then coerces (dates) is the schema's business.
+ * ChipsInput — tags as chips. Enter or comma adds, × or Backspace-on-empty
+ * removes. The value is a string[]; the schema's length/regex rules still run
+ * on submit, this is only a nicer way to type them.
  */
+declare function ChipsInput({ id, name, value, onChange, onBlur, placeholder, invalid, max }: {
+    id: string;
+    name: string;
+    value: string[];
+    onChange: (v: string[]) => void;
+    onBlur: () => void;
+    placeholder?: string;
+    invalid?: boolean;
+    /** When the schema says exactly N, show "n of N". */
+    max?: number;
+}): react.JSX.Element;
 
-/** Stand-in path for an image chosen but not yet uploaded — replaced by ADMIN-06. */
-declare const PENDING_UPLOAD_PREFIX = "pending-upload/";
-
-export { ContentForm, type ContentFormProps, type ContentFormSubmission, PENDING_UPLOAD_PREFIX };
+export { ChipsInput, ContentForm, type ContentFormProps, type ContentFormSubmission, type LabelRenderer, LengthGauge, MarkdownEditor, type MarkdownEditorProps, PENDING_UPLOAD_PREFIX, TOOLS, slugify };