themelia-react-ui 0.0.0-stage → 1.0.0

package/dist/components/features/rich-text-editor/partials/caret-helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Caret-introspection helpers used by `<RichTextEditor>` to expose the
+ * text before the caret and replace a leading run of characters with
+ * inline HTML — the building blocks for `@`-mention chips and similar
+ * inline triggers.
+ */
+import type { RichTextCaretContext, TiptapEditor } from '../rich-text-editor.types';
+/**
+ * Read the current selection's caret context.
+ *
+ * Walks back from the caret through the current text node and any
+ * preceding sibling text nodes inside the same block-level container
+ * (paragraph / list-item / heading) collecting plain text. Returns the
+ * accumulated text plus the caret's bounding rect when available.
+ *
+ * Returns `null` when there is no live selection or the selection isn't
+ * a text caret inside a contenteditable.
+ */
+export declare function readCaretContext(): RichTextCaretContext | null;
+/**
+ * Extend the selection backwards by `length` characters, then insert
+ * `html`. The selection extension means `editor.insertContent` (or the
+ * fallback's `range.deleteContents()` + insert) replaces the trigger
+ * range with the chip atomically — no manual text-content mutation, no
+ * timing races between "delete" and "insert".
+ */
+export declare function replaceBeforeCaret(editor: TiptapEditor | null, length: number, html: string, notifyChange: (next: string) => void): void;
+export declare function insertHtmlIntoEditable(editable: HTMLElement | null, html: string): void;

package/dist/components/features/rich-text-editor/partials/counts-footer.d.ts

@@ -0,0 +1,32 @@
+import type { RichTextEditorStrings } from '../rich-text-editor.strings';
+import type { TiptapEditor } from '../rich-text-editor.types';
+export interface CountsFooterTextProps {
+    /** Plain-text projection of the document, used for the character count. */
+    text: string;
+    /** Character cap the count is measured against. */
+    maxLength?: number;
+    /** Overrides this surface's own copy. */
+    strings: RichTextEditorStrings;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function CountsFooterText({ text, maxLength, strings, className }: CountsFooterTextProps): import("react").JSX.Element;
+export declare namespace CountsFooterText {
+    var displayName: string;
+}
+export interface CountsFooterProps {
+    /** The editor instance, for reading counts directly. */
+    editor: TiptapEditor;
+    /** Whether the editor is showing HTML source. */
+    sourceMode: boolean;
+    /** Raw HTML while in source mode. */
+    sourceValue: string;
+    /** Character cap the count is measured against. */
+    maxLength?: number;
+    /** Overrides this surface's own copy. */
+    strings: RichTextEditorStrings;
+}
+export declare function CountsFooter({ editor, sourceMode, sourceValue, maxLength, strings, }: CountsFooterProps): import("react").JSX.Element;
+export declare namespace CountsFooter {
+    var displayName: string;
+}

package/dist/components/features/rich-text-editor/partials/html-helpers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Plain HTML normalization shared by the TipTap and contenteditable
+ * fallback editors. Keeping these out of the React tree means the
+ * editor partials stay focused on rendering.
+ */
+export declare function normalizeHtml(value: string): string;
+export declare function toEditorContent(value: string): string;

package/dist/components/features/rich-text-editor/partials/index.d.ts

@@ -0,0 +1,7 @@
+export { RichTextEditorToolbar, type RichTextEditorToolbarProps, } from './rich-text-editor-toolbar';
+export { TiptapRichTextEditor, hasTiptapRuntime } from './rich-text-editor-tiptap';
+export { FallbackRichTextEditor } from './rich-text-editor-fallback';
+export { CountsFooter, CountsFooterText } from './counts-footer';
+export type { CountsFooterProps, CountsFooterTextProps } from './counts-footer';
+export { readCaretContext, replaceBeforeCaret, insertHtmlIntoEditable, } from './caret-helpers';
+export { normalizeHtml, toEditorContent } from './html-helpers';

package/dist/components/features/rich-text-editor/partials/rich-text-editor-fallback.d.ts

@@ -0,0 +1,8 @@
+import type { RichTextEditorHandle, RichTextEditorProps } from '../rich-text-editor.types';
+/**
+ * Fallback editor used when the TipTap runtime is unavailable (e.g. in
+ * environments where the package failed to load). Renders a
+ * `contenteditable` surface with the same imperative handle so callers
+ * never need to care which variant they got.
+ */
+export declare const FallbackRichTextEditor: import("react").ForwardRefExoticComponent<RichTextEditorProps & import("react").RefAttributes<RichTextEditorHandle>>;

package/dist/components/features/rich-text-editor/partials/rich-text-editor-tiptap.d.ts

@@ -0,0 +1,3 @@
+import type { RichTextEditorHandle, RichTextEditorProps } from '../rich-text-editor.types';
+export declare const TiptapRichTextEditor: import("react").ForwardRefExoticComponent<RichTextEditorProps & import("react").RefAttributes<RichTextEditorHandle>>;
+export declare const hasTiptapRuntime: boolean;

package/dist/components/features/rich-text-editor/partials/rich-text-editor-toolbar.d.ts

@@ -0,0 +1,33 @@
+import type { ReactNode } from 'react';
+import type { RichTextEditorStrings } from '../rich-text-editor.strings';
+import type { RichTextEditorToolbarItem, ToolbarButtonConfig } from '../rich-text-editor.types';
+export interface RichTextEditorToolbarProps {
+    /** Formatting controls to show, in order. */
+    buttons: ToolbarButtonConfig[];
+    /** Additional controls appended to the toolbar. */
+    extraToolbarItems?: ReadonlyArray<RichTextEditorToolbarItem>;
+    /** Hides the control that switches to HTML source. */
+    hideSourceToggle?: boolean;
+    /** Whether the editor is currently showing HTML source. */
+    sourceMode: boolean;
+    /** Switches between rich text and HTML source. */
+    toggleSourceMode: () => void;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /**
+     * The TipTap variant disables built-in buttons until the editor instance
+     * is ready; the fallback variant simply marks them disabled. This flag
+     * lets callers force the disabled state without re-deriving it per button.
+     */
+    hasEditor?: boolean;
+    /** Content pinned to the end of the toolbar. */
+    toolbarTrailing?: ReactNode;
+    /** Overrides this surface's own copy. */
+    strings: RichTextEditorStrings;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function RichTextEditorToolbar({ buttons, extraToolbarItems, hideSourceToggle, sourceMode, toggleSourceMode, disabled, hasEditor, toolbarTrailing, strings, className, }: RichTextEditorToolbarProps): import("react").JSX.Element;
+export declare namespace RichTextEditorToolbar {
+    var displayName: string;
+}

package/dist/components/features/rich-text-editor/rich-text-editor.d.ts

@@ -0,0 +1,3 @@
+import type { RichTextEditorHandle, RichTextEditorProps } from './rich-text-editor.types';
+export declare const RichTextEditor: import("react").ForwardRefExoticComponent<RichTextEditorProps & import("react").RefAttributes<RichTextEditorHandle>>;
+export type { RichTextEditorProps, RichTextEditorHandle, RichTextEditorToolbarItem, RichTextCaretContext, } from './rich-text-editor.types';

package/dist/components/features/rich-text-editor/rich-text-editor.recipes.d.ts

@@ -0,0 +1,6 @@
+/** Shared field anatomy for rich editors, including specialized document schemas. */
+export declare const richTextEditorRecipes: {
+    readonly frame: "min-w-0 overflow-hidden border-input bg-background rounded-radius border";
+    readonly disabled: "opacity-70";
+    readonly content: "h-full [&_.ProseMirror]:h-full [&_.ProseMirror]:min-h-full [&_.ProseMirror]:outline-none";
+};

package/dist/components/features/rich-text-editor/rich-text-editor.strings.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Default user-facing strings for `<RichTextEditor>`.
+ *
+ * Consumers wire backend i18n at the call site:
+ *
+ *   <RichTextEditor strings={{ toolbar: { bold: t('editor.bold') } }} … />
+ */
+export interface RichTextEditorStrings {
+    /** Accessible label for the editable rich-text surface. */
+    editorLabel: string;
+    /** Accessible label for the HTML source textarea. */
+    sourceLabel: string;
+    /** Toolbar button labels (used for `aria-label` and tooltip `title`). */
+    toolbar: {
+        bold: string;
+        italic: string;
+        strike: string;
+        bulletList: string;
+        orderedList: string;
+        blockquote: string;
+        undo: string;
+        redo: string;
+        sourceCode: string;
+    };
+    /** Footer count labels — `{n}` is replaced with the count. */
+    counts: {
+        characters: string;
+        words: string;
+        max: string;
+    };
+}
+export declare const defaultRichTextEditorStrings: RichTextEditorStrings;

package/dist/components/features/rich-text-editor/rich-text-editor.types.d.ts

@@ -0,0 +1,111 @@
+import type { ComponentType, ReactNode } from 'react';
+import type * as TiptapReact from '@tiptap/react';
+import type { StringsProp } from '../../../lib/strings';
+import type { RichTextEditorStrings } from './rich-text-editor.strings';
+export type TiptapEditor = NonNullable<ReturnType<typeof TiptapReact.useEditor>>;
+/**
+ * Snapshot of the text immediately before the caret — used by parents
+ * who need to detect inline triggers like `@` mentions.
+ */
+export interface RichTextCaretContext {
+    /** Plain text from the start of the current text node up to the caret. */
+    textBefore: string;
+    /** Bounding rect of the caret in viewport coordinates (when available). */
+    rect?: {
+        top: number;
+        left: number;
+        bottom: number;
+        right: number;
+    };
+}
+/**
+ * Imperative handle exposed via `ref` — lets the parent insert content,
+ * focus, and read/write the underlying HTML without owning a TipTap
+ * instance. Used by `<CommentComposer>` to insert reference chips inline.
+ */
+export interface RichTextEditorHandle {
+    focus(): void;
+    getHTML(): string;
+    setHTML(html: string): void;
+    /** Inserts raw HTML at the current selection. */
+    insertHTML(html: string): void;
+    /** True when the editor's text content is empty. */
+    isEmpty(): boolean;
+    /** Imperative clear — same as `setHTML('')`. */
+    clear(): void;
+    /** Read the text before the caret and (best-effort) the caret rect. */
+    getCaretContext(): RichTextCaretContext | null;
+    /**
+     * Delete the `length` characters immediately before the caret, then
+     * insert `html`. Used to swap a `@needle` trigger for a chip.
+     */
+    replaceBeforeCaret(length: number, html: string): void;
+}
+export interface RichTextEditorToolbarItem {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Leading glyph. */
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    /** Display label. */
+    label: string;
+    onClick: () => void;
+    isActive?: () => boolean;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+}
+export interface RichTextEditorProps {
+    /** Editor content as HTML. Controlled. */
+    value: string;
+    /** Fired with the next value. */
+    onValueChange: (html: string) => void;
+    /** Shown while the document is empty. */
+    placeholder?: string;
+    /** Tightens the toolbar and body for inline use. */
+    compact?: boolean;
+    /** Smallest height the body may take. */
+    minHeight?: string;
+    /** Height at which the body starts scrolling. */
+    maxHeight?: string;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Show character and word counts in a footer bar. */
+    showCounts?: boolean;
+    /** Optional character limit — displayed as "X / max" when showCounts is true. */
+    maxLength?: number;
+    /** Additional toolbar buttons rendered after the built-ins. */
+    extraToolbarItems?: ReadonlyArray<RichTextEditorToolbarItem>;
+    /** Slot rendered at the right edge of the toolbar (e.g. submit button). */
+    toolbarTrailing?: ReactNode;
+    /** Slot rendered below the editor (e.g. attachment chips). */
+    footerSlot?: ReactNode;
+    /** Hide the built-in source-mode toggle. Default: false. */
+    hideSourceToggle?: boolean;
+    /** Auto-focus on mount. */
+    autoFocus?: boolean;
+    /** Override class on the outer wrapper. */
+    className?: string;
+    /**
+     * Fires after every input or selection change. The parent can call
+     * `ref.current?.getCaretContext()` to inspect the caret — used by the
+     * comment composer to detect `@`-style trigger characters.
+     */
+    onCaretChange?: () => void;
+    /** Per-instance string overrides (deep-merged over `defaultRichTextEditorStrings`). */
+    strings?: StringsProp<RichTextEditorStrings>;
+}
+export interface ToolbarButtonConfig {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Leading glyph. */
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    /** Display label. */
+    label: string;
+    isActive: () => boolean;
+    run: () => void;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+}

package/dist/components/features/schema-form/hooks/index.d.ts

@@ -0,0 +1 @@
+export { useSchemaForm, type UseSchemaFormOptions, type UseSchemaFormResult, } from './use-schema-form';

package/dist/components/features/schema-form/hooks/use-schema-form.d.ts

@@ -0,0 +1,23 @@
+import type { SchemaFormErrors, SchemaFormField, SchemaFormSubmitHelpers, SchemaFormValue, SchemaFormValues } from '../schema-form.types';
+export interface UseSchemaFormOptions {
+    fields: SchemaFormField[];
+    value?: SchemaFormValues;
+    defaultValue?: SchemaFormValues;
+    errors?: SchemaFormErrors;
+    onValueChange?: (values: SchemaFormValues) => void;
+    onFieldChange?: (key: string, value: SchemaFormValue, values: SchemaFormValues) => void;
+    formatRequiredError: (label: string) => string;
+    validationError: string;
+    onError?: (error: unknown) => void;
+}
+export interface UseSchemaFormResult extends SchemaFormSubmitHelpers {
+    values: SchemaFormValues;
+    errors: SchemaFormErrors;
+    getFieldError: (key: string) => string | undefined;
+    getFieldValue: (key: string) => SchemaFormValue;
+    setFieldValue: (key: string, value: SchemaFormValue) => void;
+    setValues: (values: SchemaFormValues) => void;
+    reset: () => SchemaFormValues;
+    validate: () => boolean;
+}
+export declare function useSchemaForm({ fields, value, defaultValue, errors: externalErrors, onValueChange, onFieldChange, formatRequiredError, validationError, onError, }: UseSchemaFormOptions): UseSchemaFormResult;

package/dist/components/features/schema-form/index.d.ts

@@ -0,0 +1,5 @@
+export { SchemaForm } from './schema-form';
+export { defaultSchemaFormStrings, type SchemaFormStrings, } from './schema-form.strings';
+export type { ResolvedSchemaFormSection, SchemaFormCheckboxCardsField, SchemaFormErrors, SchemaFormField, SchemaFormFieldBase, SchemaFormFieldContext, SchemaFormFieldRender, SchemaFormFieldType, SchemaFormFieldWidth, SchemaFormJsonField, SchemaFormLayout, SchemaFormNumberField, SchemaFormOption, SchemaFormPrimitiveValue, SchemaFormProps, SchemaFormRadioCardsField, SchemaFormRenderFieldContext, SchemaFormRenderSectionContext, SchemaFormSchema, SchemaFormSection, SchemaFormSelectField, SchemaFormStructuredValue, SchemaFormSubmitHelpers, SchemaFormSwitchField, SchemaFormTagsField, SchemaFormTextField, SchemaFormTextareaField, SchemaFormValue, SchemaFormValues, SchemaFormValidator, } from './schema-form.types';
+export { useSchemaForm, type UseSchemaFormOptions, type UseSchemaFormResult, } from './hooks';
+export { SchemaFormActions, SchemaFormEmpty, SchemaFormFieldRenderer, type SchemaFormActionsProps, type SchemaFormEmptyProps, type SchemaFormFieldRendererProps, } from './partials';

package/dist/components/features/schema-form/partials/index.d.ts

@@ -0,0 +1,3 @@
+export { SchemaFormActions, type SchemaFormActionsProps } from './schema-form-actions';
+export { SchemaFormEmpty, type SchemaFormEmptyProps } from './schema-form-empty';
+export { SchemaFormFieldRenderer, type SchemaFormFieldRendererProps } from './schema-form-field';

package/dist/components/features/schema-form/partials/schema-form-actions.d.ts

@@ -0,0 +1,23 @@
+export interface SchemaFormActionsProps {
+    /** Copy for the submit button. */
+    submitLabel: string;
+    /** Copy for the reset button. */
+    resetLabel: string;
+    /** Renders the reset. */
+    showReset?: boolean;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Disables the submit button. */
+    submitDisabled?: boolean;
+    /** Disables the reset button. */
+    resetDisabled?: boolean;
+    /** Shows the pending state on submit. */
+    submitting?: boolean;
+    onReset?: () => void;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function SchemaFormActions({ submitLabel, resetLabel, showReset, disabled, submitDisabled, resetDisabled, submitting, onReset, className, }: SchemaFormActionsProps): import("react").JSX.Element;
+export declare namespace SchemaFormActions {
+    var displayName: string;
+}

package/dist/components/features/schema-form/partials/schema-form-empty.d.ts

@@ -0,0 +1,12 @@
+export interface SchemaFormEmptyProps {
+    /** Surface title. */
+    title: string;
+    /** Supporting copy shown under the label. */
+    description: string;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function SchemaFormEmpty({ title, description, className }: SchemaFormEmptyProps): import("react").JSX.Element;
+export declare namespace SchemaFormEmpty {
+    var displayName: string;
+}

package/dist/components/features/schema-form/partials/schema-form-field.d.ts

@@ -0,0 +1,12 @@
+import type { SchemaFormStrings } from '../schema-form.strings';
+import type { SchemaFormFieldContext } from '../schema-form.types';
+export interface SchemaFormFieldRendererProps extends SchemaFormFieldContext {
+    /** Overrides this surface's own copy. */
+    strings: SchemaFormStrings;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export declare function SchemaFormFieldRenderer({ field, value, values, error, disabled, required, fieldId, onValueChange, onError, strings, className, }: SchemaFormFieldRendererProps): import("react").JSX.Element;
+export declare namespace SchemaFormFieldRenderer {
+    var displayName: string;
+}

package/dist/components/features/schema-form/schema-form.d.ts

@@ -0,0 +1,5 @@
+import type { SchemaFormProps } from './schema-form.types';
+export declare function SchemaForm({ schema, value, defaultValue, errors, disabled, layout, columns, id, name, title, description, headerSlot, footerSlot, actionsSlot, emptySlot, showActions, submitLabel, resetLabel, submitDisabled, resetDisabled, submitting, onValueChange, onFieldChange, onSubmit, onReset, onError, renderField, renderSection, strings: stringsProp, className, contentClassName, sectionClassName, fieldClassName, }: SchemaFormProps): import("react").JSX.Element;
+export declare namespace SchemaForm {
+    var displayName: string;
+}

package/dist/components/features/schema-form/schema-form.strings.d.ts

@@ -0,0 +1,11 @@
+export interface SchemaFormStrings {
+    submitLabel: string;
+    resetLabel: string;
+    defaultSectionTitle: string;
+    emptyTitle: string;
+    emptyDescription: string;
+    jsonParseError: string;
+    validationError: string;
+    formatRequiredError: (label: string) => string;
+}
+export declare const defaultSchemaFormStrings: SchemaFormStrings;