vue-fillable-text

vue-fillable-text

Typed Vue 3 components for documents that mix prose with interactive input and select gaps. It is the Vue counterpart of react-fillable-text and uses the same version 1 document schema.

Installation

npm install vue-fillable-text

Import the styles once:

import "vue-fillable-text/styles.css";

Quick start

<script setup lang="ts">
import { ref } from "vue";
import { FillableText, type FillableDocument, type FillableValues } from "vue-fillable-text";
import "vue-fillable-text/styles.css";

const document: FillableDocument = {
  version: 1,
  content: [
    { type: "text", text: "The capital of France is " },
    { type: "gap", id: "capital", control: "input", originalText: "Paris", placeholder: "Enter a city…" },
    { type: "text", text: "." },
  ],
};
const values = ref<FillableValues>({});
</script>

<template>
  <FillableText v-model="values" :document="document" @gap-change="(id, value) => console.log(id, value)" />
</template>

Editor

<script setup lang="ts">
import { ref } from "vue";
import { FillableTextEditor, type FillableDocument } from "vue-fillable-text";

const document = ref<FillableDocument>({ version: 1, content: [{ type: "text", text: "Select text to create a gap." }] });
</script>

<template><FillableTextEditor v-model="document" /></template>

The editor supports input and select gaps, plain-text paste, keyboard deletion, and undo/redo with Cmd/Ctrl+Z and Cmd/Ctrl+Shift+Z.

Components and events

• FillableText: v-model contains answers; accepts document, disabled, gapStates, getGapState, and components; emits gap-change.
• FillableTextEditor: v-model contains the document; also supports uncontrolled use with defaultValue; emits change, gap-create, gap-update, gap-remove, and selection-change.
• Custom controls receive modelValue, id, state, disabled, ariaLabel, plus placeholder or options, and must emit update:modelValue.
• Core helpers: createGap, updateGap, removeGap, deleteGap, serialize, deserialize, validateDocument, and toPlainText.

Documents can be exchanged directly with react-fillable-text; answers are deliberately stored separately.

Development

npm install
npm test
npm run typecheck
npm run build
npm pack --dry-run

Publishing

Releases are handled by GitLab CI with the same token-based flow as react-fillable-text:

• pushes produced by merges into develop stage a unique prerelease such as 0.1.1-develop.123 under the develop tag;
• pushes produced by merges into main automatically increment the latest published patch version and publish it, for example 0.1.0 → 0.1.1.

Release versions are calculated from the current latest version in the npm registry. CI changes the manifests only inside the ephemeral runner; generated version changes are not committed back to the repository.

GitLab must provide a protected, masked NPM_TOKEN variable with Read and write (publish and stage) permission. Both main and develop must be protected branches so their release jobs can access the protected variable.

After a successful stable publication, CI creates a merge request from main into develop. Configure a second protected, masked variable named GITLAB_API_TOKEN using a GitLab project access token (Developer or higher) or a personal access token with the api scope. If an open main → develop merge request already exists, CI reuses it instead of creating a duplicate.

The prepublishOnly hook runs tests, type checking, and the production build before publishing.

License

MIT