@case-framework/survey-ui 0.2.3 → 0.3.0

package/README.md

@@ -1,73 +1,40 @@
-# React + TypeScript + Vite
+# @case-framework/survey-ui
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+React UI components for CASE surveys, including the `SurveyEditor`.
 
-Currently, two official plugins are available:
+## SurveyEditor styling in a host project
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+Import the package stylesheet once in your app entry point:
 
-## React Compiler
+```tsx
+import "@case-framework/survey-ui/css";
+```
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+If you only want the editor's default variable values as a tiny standalone asset, import:
 
-## Expanding the ESLint configuration
+```tsx
+import "@case-framework/survey-ui/editor-defaults.css";
+```
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+`@case-framework/survey-ui/css` already includes these defaults, so the standalone file is only needed when the host wants a separate variables-only layer.
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+If the host app uses Tailwind CSS v4, add the package as a source in the host global CSS file so Tailwind also scans the editor package:
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+```css
+@import "tailwindcss";
+@source "../node_modules/@case-framework/survey-ui/dist";
+```
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+Override the editor-specific CSS variables on the `.survey-editor` scope in the host stylesheet:
+
+```css
+.survey-editor {
+  --surface-bg-color: oklch(1 0 0);
+}
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
+Available editor-scoped variables:
 
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
+- `--surface-bg-color`
 
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
-```
+The editor also uses the shared UI theme tokens from the package stylesheet, so you can override variables such as `--background`, `--foreground`, `--card`, `--primary`, `--muted`, `--accent`, `--border`, `--input`, and `--ring` if you want the rest of the editor chrome to match your host theme.

package/dist/index.d.ts

@@ -1,478 +1 @@
-import { Accept } from 'react-dropzone';
-import { BuildSurveyAIContextPackOptions } from '@case-framework/survey-core/editor';
-import { ClassProp } from 'class-variance-authority/types';
-import { default as default_2 } from 'react';
-import { FileRejection } from 'react-dropzone';
-import { FileWithPath } from 'react-dropzone';
-import { ItemCoreConstructor } from '@case-framework/survey-core';
-import { ItemTypeRegistry } from '@case-framework/survey-core';
-import { JSX } from 'react/jsx-runtime';
-import { RawSurveyItem } from '@case-framework/survey-core';
-import { RenderedSurveyItem } from '@case-framework/survey-core';
-import { SerializedSurveyEditor } from '@case-framework/survey-core/editor';
-import { Survey } from '@case-framework/survey-core';
-import { SurveyAIContextIndexes } from '@case-framework/survey-core/editor';
-import { SurveyAIContextPack } from '@case-framework/survey-core/editor';
-import { SurveyAIContextPurpose } from '@case-framework/survey-core/editor';
-import { SurveyAIContextScope } from '@case-framework/survey-core/editor';
-import { SurveyAIFocus } from '@case-framework/survey-core/editor';
-import { SurveyAIItemContextNode } from '@case-framework/survey-core/editor';
-import { SurveyAIKeyIndexEntry } from '@case-framework/survey-core/editor';
-import { SurveyAIOutlineNode } from '@case-framework/survey-core/editor';
-import { SurveyAITranslationSnippet } from '@case-framework/survey-core/editor';
-import { SurveyItemCore } from '@case-framework/survey-core';
-import { SurveyItemTranslations } from '@case-framework/survey-core';
-import { Target } from '@case-framework/survey-core/editor';
-import { VariantProps } from 'class-variance-authority';
-
-export declare interface AISuggestedText {
-    text: string;
-}
-
-export declare interface BuildSurveyAIContextOptions {
-    purpose?: SurveyAIContextPurpose;
-    scope?: SurveyAIContextScope;
-    focusItemId?: string;
-    includeRawSurvey?: boolean;
-    outlineLimit?: number;
-    includeIndexes?: boolean;
-    includeFocusItemTree?: boolean;
-    focusItemTreeLimit?: number;
-    translationSnippetsPerItemLimit?: number;
-    translationSnippetTextLimit?: number;
-}
-
-export { BuildSurveyAIContextPackOptions }
-
-export declare function buildSurveyFileName(state: SerializedSurveyEditor, fallback?: string): string;
-
-export declare function cloneRegistryEntries(entries: readonly ItemRegistryEntry[]): ItemRegistryEntry[];
-
-export declare interface ComposedEditorItemRegistry {
-    coreRegistry: ItemTypeRegistry;
-    definitions: EditorItemDefinitionRegistry;
-}
-
-export declare function createBlankEditorState(pluginRegistry?: ItemTypeRegistry, surveyKey?: string): SerializedSurveyEditor;
-
-export declare function createComposedEditorRegistry(options?: CreateComposedEditorRegistryOptions): ComposedEditorItemRegistry;
-
-export declare type CreateComposedEditorRegistryOptions = CreateRegistryEntriesOptions & EntriesToComposedEditorRegistryOptions;
-
-export declare function createEditorStateFromRawSurvey(rawSurvey: Parameters<typeof Survey.fromJson>[0], pluginRegistry?: ItemTypeRegistry): SerializedSurveyEditor;
-
-declare interface CreateItemContext {
-    editor: {
-        addItem: (target: Target, item: SurveyItemCore, content?: SurveyItemTranslations) => void;
-    };
-    targetParentId: string;
-    constructor: ItemCoreConstructor;
-}
-
-export declare function createRegistryEntries(options?: CreateRegistryEntriesOptions): ItemRegistryEntry[];
-
-export declare interface CreateRegistryEntriesOptions {
-    /** Include default built-in entries first. Defaults to true. */
-    includeDefaultEntries?: boolean;
-    /** Custom entries to add/override. */
-    entries?: ItemRegistryEntry[];
-    /** How to handle duplicate itemType values. Defaults to override. */
-    conflictStrategy?: RegistryConflictStrategy;
-}
-
-export declare function createSurveyPlayerRegistry(options?: CreateSurveyPlayerRegistryOptions): SurveyPlayerItemRegistry;
-
-export declare type CreateSurveyPlayerRegistryOptions = CreateRegistryEntriesOptions & EntriesToParticipantRegistryOptions;
-
-export declare interface EditorItemDefinition {
-    itemType: string;
-    infos: ItemInfos;
-    editorComponent?: default_2.ComponentType<ItemEditorComponentProps>;
-    renderComponent?: default_2.ComponentType<ItemRendererComponentProps>;
-    previewComponent?: default_2.ComponentType<ItemPreviewComponentProps>;
-    capabilities?: ItemEditorCapabilities;
-    isRootOnly?: boolean;
-    getInitialItem?: () => ItemInitialData;
-    createItem?: (ctx: CreateItemContext) => string;
-    searchAdapters?: ItemSearchAdapter[];
-    includeDefaultSearchAdapter?: boolean;
-}
-
-export declare type EditorItemDefinitionRegistry = Record<string, EditorItemDefinition>;
-
-declare interface EditorItemSearchResult {
-    matchType: SearchMatchType;
-    matchText: string;
-}
-
-declare interface EditorStateChangePayload {
-    sessionId: string | null;
-    state: SerializedSurveyEditor;
-    revision: number;
-    hasUncommittedChanges: boolean;
-    at: number;
-}
-
-/**
- * Derive ComposedEditorItemRegistry from unified entries for the editor.
- * Ensures Group and PageBreak have definitions; uses coreRegistry from entries.
- */
-export declare function entriesToComposedEditorRegistry(entries: ItemRegistryEntry[], options?: EntriesToComposedEditorRegistryOptions): ComposedEditorItemRegistry;
-
-export declare interface EntriesToComposedEditorRegistryOptions {
-    /** Require built-in editor definitions for group/pageBreak. Defaults to true. */
-    requireBuiltInTypes?: boolean;
-}
-
-/**
- * Derive ItemTypeRegistry from unified entries for Survey / SurveyEditor.
- * Uses built-in registry for group/pageBreak; plugin entries supply constructors for custom types.
- */
-export declare function entriesToItemTypeRegistry(entries: ItemRegistryEntry[]): ItemTypeRegistry;
-
-/**
- * Derive participant registry from unified entries.
- * Lightweight: core + renderer only. Use this for survey player / participant app.
- */
-export declare function entriesToParticipantRegistry(entries: ItemRegistryEntry[], options?: EntriesToParticipantRegistryOptions): SurveyPlayerItemRegistry;
-
-export declare interface EntriesToParticipantRegistryOptions {
-    /** Throw when an entry in the provided list does not define a renderComponent. */
-    requireRenderer?: boolean;
-}
-
-declare function Field({ className, orientation, ...props }: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>): JSX.Element;
-
-declare const fieldVariants: (props?: ({
-    orientation?: "horizontal" | "vertical" | "responsive" | null | undefined;
-} & ClassProp) | undefined) => string;
-
-export declare function FilepickerDropzone({ id, name, label, description, error, accept, multiple, disabled, required, maxFiles, maxSize, minSize, icon, className, labelClassName, contentClassName, descriptionClassName, errorClassName, dropzoneClassName, labels, onChange, onDropRejected, ...props }: FilepickerDropzoneProps): JSX.Element;
-
-export declare interface FilepickerDropzoneLabels {
-    upload: string;
-    drag: string;
-    active: string;
-    reject: string;
-    rejectInvalidType: string;
-    rejectTooLarge: string;
-    rejectTooSmall: string;
-    rejectTooMany: string;
-    selectedCount: string;
-}
-
-export declare interface FilepickerDropzoneProps extends Omit<React.ComponentProps<typeof Field>, "children" | "onChange"> {
-    id: string;
-    name?: string;
-    label?: React.ReactNode;
-    description?: React.ReactNode;
-    error?: React.ReactNode;
-    accept?: Accept;
-    multiple?: boolean;
-    disabled?: boolean;
-    required?: boolean;
-    maxFiles?: number;
-    maxSize?: number;
-    minSize?: number;
-    icon?: React.ReactNode;
-    labelClassName?: string;
-    contentClassName?: string;
-    descriptionClassName?: string;
-    errorClassName?: string;
-    dropzoneClassName?: string;
-    labels?: Partial<FilepickerDropzoneLabels>;
-    onChange?: (files: readonly FileWithPath[]) => void;
-    onDropRejected?: (fileRejections: FileRejection[]) => void;
-}
-
-export declare interface GeneratedItemIntentSuggestion {
-    tempId: string;
-    parentTempId?: string;
-    itemType: string;
-    key: string;
-    itemLabel?: string;
-    confidence?: number;
-}
-
-export declare interface GenerateItemFromIntentRequest {
-    intent: string;
-    targetParentId: string;
-    allowedItemTypes: string[];
-    maxItems?: number;
-    locale?: string;
-    context: SurveyAIContextPack;
-}
-
-export declare interface GenerateItemFromIntentResult {
-    items: GeneratedItemIntentSuggestion[];
-}
-
-export declare function getDefaultComposedEditorRegistry(): ComposedEditorItemRegistry;
-
-export declare function getDefaultRegistryEntries(): ItemRegistryEntry[];
-
-export declare function getDefaultSurveyPlayerRegistry(): SurveyPlayerItemRegistry;
-
-declare type ItemCategory = string;
-
-declare interface ItemEditorCapabilities {
-    usesValidationPanel?: boolean;
-    usesTranslationPanel?: boolean;
-    usesConditionsPanel?: boolean;
-}
-
-export declare interface ItemEditorComponentProps<TItem extends SurveyItemCore = SurveyItemCore> {
-    item: TItem;
-}
-
-declare interface ItemEditorLocation {
-    view: 'item-editor';
-    itemId?: string;
-}
-
-export declare type ItemIconComponent = default_2.ComponentType<{
-    className?: string;
-}>;
-
-declare interface ItemInfos {
-    icon: ItemIconComponent;
-    labelByLocale: ItemLocaleMap;
-    descriptionByLocale: ItemLocaleMap;
-    defaultItemClassName?: string;
-    categories: ItemCategory[];
-}
-
-declare interface ItemInitialData {
-    rawItem: RawSurveyItem;
-    translations?: SurveyItemTranslations;
-    children?: ItemInitialData[];
-}
-
-declare type ItemLocaleMap = Record<string, string>;
-
-export declare interface ItemPreviewComponentProps<TItem extends SurveyItemCore = SurveyItemCore> {
-    item: TItem;
-    itemConfig: TItem["config"];
-    itemContent?: SurveyItemTranslations;
-    locale: string;
-    mode?: ItemPreviewMode;
-}
-
-export declare type ItemPreviewMode = "interactive" | "static";
-
-/**
- * Unified registry entry type, reusable across contexts:
- *
- * - Participant app: needs only `constructor` + `renderComponent`
- * - Editor: needs constructor, infos, `previewComponent`, editorComponent, searchAdapters, etc.
- *
- * Use the mapper helpers to derive ItemTypeRegistry, participant registry, or editor registry.
- */
-export declare interface ItemRegistryEntry {
-    itemType: string;
-    /** Item core constructor. Omit for built-in types (group, pageBreak) — they use survey-core's built-in registry. Omit for virtual "root" — it maps to Group with isRoot. */
-    constructor?: ItemCoreConstructor;
-    /** Participant renderer. Required for participant app. */
-    renderComponent?: default_2.ComponentType<ItemRendererComponentProps>;
-    /** Editor-only: item preview renderer */
-    previewComponent?: default_2.ComponentType<ItemPreviewComponentProps>;
-    /** Editor-only: display metadata */
-    infos?: ItemInfos;
-    /** Editor-only: card/editor UI */
-    editorComponent?: default_2.ComponentType<ItemEditorComponentProps>;
-    /** Editor-only: search integration */
-    searchAdapters?: ItemSearchAdapter[];
-    /** Editor-only: include built-in key/label/itemType search adapter in addition to custom adapters. Defaults to true. */
-    includeDefaultSearchAdapter?: boolean;
-    /** Editor-only */
-    capabilities?: ItemEditorCapabilities;
-    /** Editor-only: default raw item when creating new */
-    getInitialItem?: () => ItemInitialData;
-    /** Editor-only: custom creation flow (advanced) */
-    createItem?: (ctx: CreateItemContext) => string;
-    /** Editor-only: hide from add-item options in non-root context */
-    isRootOnly?: boolean;
-}
-
-export declare interface ItemRendererComponentProps {
-    renderedItem: RenderedSurveyItem;
-}
-
-export declare type ItemSearchAdapter = (ctx: ItemSearchAdapterContext) => EditorItemSearchResult[] | undefined;
-
-declare interface ItemSearchAdapterContext {
-    itemId: string;
-    survey: Survey;
-    searchTerm: string;
-}
-
-export declare interface ParsedSurveySession {
-    format: ParsedSurveySessionFormat;
-    state: SerializedSurveyEditor;
-    sessionId: string;
-}
-
-export declare type ParsedSurveySessionFormat = 'raw-survey' | 'serialized-editor';
-
-export declare function parseEditorStateFromJsonText(jsonText: string, pluginRegistry?: ItemTypeRegistry): ParsedSurveySession;
-
-export declare type RegistryConflictStrategy = "error" | "override";
-
-export declare interface RegistryValidationIssue {
-    code: string;
-    message: string;
-    itemType?: string;
-}
-
-export declare type RegistryValidationMode = "editor" | "player";
-
-export declare interface RegistryValidationOptions {
-    mode: RegistryValidationMode;
-    requireBuiltInTypes?: boolean;
-    requireRenderer?: boolean;
-}
-
-export declare interface RegistryValidationResult {
-    errors: RegistryValidationIssue[];
-    warnings: RegistryValidationIssue[];
-}
-
-declare const SearchMatchType: {
-    readonly Content: "content";
-    readonly Label: "label";
-    readonly Key: "key";
-    readonly ItemType: "itemType";
-};
-
-declare type SearchMatchType = (typeof SearchMatchType)[keyof typeof SearchMatchType];
-
-export declare function serializeSurveyStateForFile(state: SerializedSurveyEditor): string;
-
-declare interface SimulatorLocation {
-    view: 'simulator';
-}
-
-export declare interface SuggestItemKeyRequest {
-    draftKey: string;
-    currentKey: string;
-    siblingKeys: string[];
-    childContentHints?: string[];
-    maxSuggestions?: number;
-    context: SurveyAIContextPack;
-}
-
-export declare interface SuggestItemKeyResult {
-    suggestions: SuggestItemKeySuggestion[];
-}
-
-export declare interface SuggestItemKeySuggestion extends AISuggestedText {
-    rationale?: string;
-}
-
-export declare interface SuggestItemLabelRequest {
-    draftLabel: string;
-    itemType: string;
-    locale?: string;
-    maxSuggestions?: number;
-    context: SurveyAIContextPack;
-}
-
-export declare interface SuggestItemLabelResult {
-    suggestions: SuggestItemLabelSuggestion[];
-}
-
-export declare interface SuggestItemLabelSuggestion extends AISuggestedText {
-    tone?: string;
-}
-
-export { SurveyAIContextIndexes }
-
-export { SurveyAIContextPack }
-
-export { SurveyAIContextPurpose }
-
-export { SurveyAIContextScope }
-
-export { SurveyAIFocus }
-
-export declare type SurveyAIInvocationMode = "user" | "background";
-
-export { SurveyAIItemContextNode }
-
-export { SurveyAIKeyIndexEntry }
-
-export { SurveyAIOutlineNode }
-
-export declare interface SurveyAIRequestOptions {
-    signal?: AbortSignal;
-    mode?: SurveyAIInvocationMode;
-}
-
-export { SurveyAITranslationSnippet }
-
-export declare const SurveyEditor: React.FC<SurveyEditorProps>;
-
-export declare interface SurveyEditorAIProvider {
-    suggestItemKey?: (request: SuggestItemKeyRequest, options?: SurveyAIRequestOptions) => Promise<SuggestItemKeyResult>;
-    suggestItemLabel?: (request: SuggestItemLabelRequest, options?: SurveyAIRequestOptions) => Promise<SuggestItemLabelResult>;
-    generateItemFromIntent?: (request: GenerateItemFromIntentRequest, options?: SurveyAIRequestOptions) => Promise<GenerateItemFromIntentResult>;
-    translateContent?: (request: TranslateContentRequest, options?: SurveyAIRequestOptions) => Promise<TranslateContentResult>;
-}
-
-declare type SurveyEditorLocation = ItemEditorLocation | TranslationModeLocation | SimulatorLocation;
-
-declare interface SurveyEditorNavigationAdapter {
-    getLocation: () => SurveyEditorLocation;
-    navigateTo: (location: SurveyEditorLocation, options?: {
-        replace?: boolean;
-    }) => void;
-    subscribe(listener: (location: SurveyEditorLocation) => void): () => void;
-}
-
-export declare interface SurveyEditorProps {
-    initialEditorState?: SerializedSurveyEditor;
-    initialSessionId?: string;
-    fallbackLocale?: string;
-    itemRegistryEntries?: ItemRegistryEntry[];
-    onEditorStateChange?: (change: SurveyEditorStateChange) => void;
-    persistDebounceMs?: number;
-    helpLink?: string;
-    navigationAdapter?: SurveyEditorNavigationAdapter | null;
-    aiProvider?: SurveyEditorAIProvider | null;
-    onSaveRequested?: () => void;
-}
-
-export declare type SurveyEditorStateChange = EditorStateChangePayload;
-
-export declare const SurveyPlayer: default_2.FC;
-
-/** Participant registry: core + renderer per item type. Lightweight for survey player. */
-declare interface SurveyPlayerItemRegistry {
-    coreRegistry: ItemTypeRegistry;
-    getRenderer: (itemType: string) => default_2.ComponentType<ItemRendererComponentProps> | undefined;
-}
-
-export declare interface TranslateContentEntry {
-    id: string;
-    text: string;
-    kind: string;
-}
-
-export declare interface TranslateContentRequest {
-    sourceLocale: string;
-    targetLocales: string[];
-    entries: TranslateContentEntry[];
-    context: SurveyAIContextPack;
-}
-
-export declare interface TranslateContentResult {
-    translations: Record<string, Record<string, string>>;
-}
-
-declare interface TranslationModeLocation {
-    view: 'translation-mode';
-}
-
-export declare function validateRegistryEntries(entries: ItemRegistryEntry[], options: RegistryValidationOptions): RegistryValidationResult;
-
 export { }

package/dist/survey-editor-defaults.css

@@ -0,0 +1,15 @@
+.survey-editor {
+    /* Editor card / preview canvas — neutral near-white */
+    --surface-bg-color: oklch(99.1% 0 0);
+
+    /*
+     * Rich text emphasis (Lexical + preview). Chosen for strong contrast on
+     * --surface-bg-color and clearly distinct hues so “primary” vs “accent” reads
+     * in the UI (not tied to global --primary / --accent, which are tuned for chrome).
+     *
+     * Primary — cool / structural: main wording emphasis (question tone, lead-in).
+     * Accent — warm / focal: secondary highlight (callouts, supplementary emphasis).
+     */
+    --rich-text-editor-primary-color: oklch(0.36 0.12 264);
+    --rich-text-editor-accent-color: oklch(0.44 0.15 48);
+}