@questify/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ashish Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# @questify/core
+
+**Questify** — headless, zero-dependency questionnaire engine for the web.
+
+[![npm version](https://img.shields.io/npm/v/%40questify%2Fcore?style=flat-square)](https://www.npmjs.com/package/@questify/core)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/%40questify%2Fcore?style=flat-square)](https://bundlephobia.com/package/@questify/core)
+[![license](https://img.shields.io/npm/l/%40questify%2Fcore?style=flat-square)](./LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue?style=flat-square)](./src)
+
+**Live demo → [questify.renderlog.in](https://questify.renderlog.in)**
+
+---
+
+This package is a pure TypeScript state machine for multi-step forms and surveys.
+It ships **zero runtime dependencies** and **zero UI** — you control every pixel.
+Framework adapters for React and Vue are included.
+
+## Install
+
+```bash
+npm install @questify/core
+```
+
+## React
+
+```tsx
+import { useQuestionnaire } from '@questify/core/react';
+
+const questions = [
+  { id: 'name',   text: "What's your name?",  type: 'text',   required: true },
+  { id: 'rating', text: 'Rate us 1–5',         type: 'rating', required: true },
+  {
+    id: 'feedback',
+    text: 'What could be improved?',
+    type: 'text',
+    showIf: { questionId: 'rating', value: 3, operator: 'lte' },
+  },
+];
+
+function Survey() {
+  const { question, answer, next, back, progress, isComplete, canGoNext, canGoBack } =
+    useQuestionnaire({ questions });
+
+  if (!question) return null;
+
+  return (
+    <div>
+      <progress value={progress} max={1} />
+      <h2>{question.text}</h2>
+
+      {/* render your own inputs — questify ships no UI */}
+      {question.type === 'text' && (
+        <input onChange={(e) => answer(e.target.value)} />
+      )}
+
+      <button onClick={back} disabled={!canGoBack}>Back</button>
+      {canGoNext
+        ? <button onClick={next}>Next</button>
+        : <button disabled={!isComplete}>Submit</button>
+      }
+    </div>
+  );
+}
+```
+
+## Vue 3
+
+```vue
+<script setup lang="ts">
+import { useQuestionnaire } from '@questify/core/vue';
+const { question, answer, next, back, progress, isComplete } =
+  useQuestionnaire({ questions });
+</script>
+
+<template>
+  <div v-if="question">
+    <progress :value="progress" :max="1" />
+    <h2>{{ question.text }}</h2>
+    <input v-if="question.type === 'text'" @input="e => answer(e.target.value)" />
+    <button @click="back">Back</button>
+    <button @click="next">Next</button>
+  </div>
+</template>
+```
+
+## Vanilla JS
+
+```ts
+import { Questionnaire } from '@questify/core';
+
+const q = new Questionnaire({ questions });
+
+const unsubscribe = q.subscribe((state) => {
+  console.log(state.question?.text, state.progress);
+});
+
+q.answer('Alice');
+q.next();
+unsubscribe();
+```
+
+## Question types
+
+`text` · `email` · `number` · `boolean` · `single` · `multi` · `rating` · `date`
+
+## Conditional logic — `showIf`
+
+```ts
+// Simple
+showIf: { questionId: 'smoker', value: true }
+
+// With operator
+showIf: { questionId: 'rating', value: 3, operator: 'lte' }
+
+// Compound AND
+showIf: {
+  and: [
+    { questionId: 'age',    value: 18, operator: 'gte' },
+    { questionId: 'smoker', value: true },
+  ],
+}
+
+// Compound OR — nestable to any depth
+showIf: {
+  or: [
+    { questionId: 'urgent', value: true },
+    { and: [{ questionId: 'score', value: 5, operator: 'lte' }] },
+  ],
+}
+```
+
+Operators: `eq` · `neq` · `gt` · `lt` · `gte` · `lte` · `includes`
+
+## API
+
+### Hook / composable return value
+
+| Property | Type | Description |
+|---|---|---|
+| `question` | `Question \| null` | Current question (step mode) |
+| `visibleQuestions` | `Question[]` | All visible questions after resolving `showIf` |
+| `progress` | `number` (0–1) | Fraction of visible questions answered |
+| `responses` | `Record<string, unknown>` | All answers so far |
+| `errors` | `Record<string, string>` | Validation errors for visible questions |
+| `isComplete` | `boolean` | All required visible questions answered & valid |
+| `answer(value)` | `fn` | Answer current question (step mode) |
+| `answerById(id, value)` | `fn` | Answer any question by id (all mode) |
+| `next()` | `fn` | Advance (validates required first) |
+| `back()` | `fn` | Go back one step |
+| `jumpTo(index)` | `fn` | Jump to a step by index |
+| `validate()` | `fn` | Validate all visible fields, returns errors |
+| `reset()` | `fn` | Clear all answers and restart |
+| `getSubmittableResponses()` | `fn` | Responses for visible questions only — safe for submission |
+
+### Modes
+
+| Mode | Use case |
+|---|---|
+| `step` (default) | Wizard — one question at a time |
+| `all` | Show all questions simultaneously (accordion, long-form) |
+
+### Built-in validation
+
+- `required` — whitespace-only treated as empty
+- `min` / `max` — for `number` and `rating`
+- `minLength` / `maxLength` — for `text` and `email`
+- `regex` — for `text`
+- `email` format — always validated automatically for `type: "email"`
+- `date` format — `YYYY-MM-DD` enforced automatically for `type: "date"`
+- `number` — rejects `NaN` and `±Infinity`
+
+## License
+
+MIT © [Ashish Kumar](https://github.com/ashishcumar)

package/dist/index.d.mts

@@ -0,0 +1,132 @@
+type QuestionType = "text" | "number" | "boolean" | "single" | "multi" | "date" | "rating" | "email";
+type ConditionOperator = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "includes";
+/** A single condition against one question's response. */
+interface ShowIfCondition {
+    questionId: string;
+    value: unknown;
+    operator?: ConditionOperator;
+}
+/**
+ * Compound condition — nest `and`/`or` arrays for full branching logic.
+ *
+ * @example
+ * // Show only when user has diabetes AND is on insulin
+ * showIf: {
+ *   and: [
+ *     { questionId: 'conditions', value: 'diabetes', operator: 'includes' },
+ *     { questionId: 'on_insulin', value: true },
+ *   ]
+ * }
+ */
+interface ShowIfCompound {
+    and?: ShowIfRule[];
+    or?: ShowIfRule[];
+}
+/** A single condition OR a compound AND/OR tree — fully nestable. */
+type ShowIfRule = ShowIfCondition | ShowIfCompound;
+interface QuestionValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    regex?: string;
+    message?: string;
+}
+interface QuestionOption {
+    label: string;
+    value: string | number;
+}
+interface Question {
+    id: string;
+    text: string;
+    type: QuestionType;
+    description?: string;
+    required?: boolean;
+    placeholder?: string;
+    options?: QuestionOption[];
+    showIf?: ShowIfRule;
+    validation?: QuestionValidation;
+}
+type DisplayMode = "step" | "all";
+interface QuestionnaireConfig {
+    questions: Question[];
+    mode?: DisplayMode;
+    initialResponses?: Record<string, unknown>;
+}
+interface QuestionnaireState {
+    /** Current question (step mode). In 'all' mode, always the first visible question. */
+    question: Question | null;
+    /** All currently visible questions (after applying showIf conditions). */
+    visibleQuestions: Question[];
+    /** Zero-based index of the current question in the visible questions array. */
+    questionIndex: number;
+    /** Total number of currently visible questions. */
+    totalQuestions: number;
+    /** Progress from 0 to 1 based on how many questions have valid answers. */
+    progress: number;
+    /** All responses keyed by question id. */
+    responses: Record<string, unknown>;
+    /** True when all required visible questions have valid responses. */
+    isComplete: boolean;
+    /** Validation errors keyed by question id. */
+    errors: Record<string, string>;
+    /** Whether the user can navigate to the previous question. */
+    canGoBack: boolean;
+    /** Whether the user can navigate to the next question. */
+    canGoNext: boolean;
+}
+
+declare function validateAnswer(question: Question, value: unknown): string | null;
+type Subscriber = (state: QuestionnaireState) => void;
+declare class Questionnaire {
+    private config;
+    private responses;
+    private questionIndex;
+    private errors;
+    private subscribers;
+    private cachedState;
+    constructor(config: QuestionnaireConfig);
+    private recompute;
+    private notify;
+    getState(): QuestionnaireState;
+    /**
+     * Returns only responses for currently visible questions.
+     * Use this for form submission — avoids sending hidden-branch data to the server.
+     *
+     * `state.responses` retains all answers for back-navigation; this method prunes them.
+     */
+    getSubmittableResponses(): Record<string, unknown>;
+    subscribe(callback: Subscriber): () => void;
+    /**
+     * Answer the current question (step mode).
+     * In `mode: "all"` prefer `answerById()`.
+     */
+    answer(value: unknown): void;
+    /**
+     * Answer any visible question by its id — the right API for `mode: "all"`.
+     * Safe to call in step mode too (allows answering any step by id).
+     */
+    answerById(questionId: string, value: unknown): void;
+    private _setAnswer;
+    /**
+     * Advance to the next step (step mode).
+     * Validates the current required question first; populates `errors` if invalid.
+     */
+    next(): void;
+    /** Go to the previous step. No-op on step 0. */
+    back(): void;
+    /**
+     * Jump to a specific step index (0-based, within visible questions).
+     * Out-of-range indices are silently ignored.
+     */
+    jumpTo(index: number): void;
+    /**
+     * Validate all visible required questions and return a map of errors.
+     * Useful for "submit" gates in `mode: "all"`.
+     */
+    validate(): Record<string, string>;
+    /** Reset all responses and errors, restart from step 0. */
+    reset(): void;
+}
+
+export { type ConditionOperator, type DisplayMode, type Question, type QuestionOption, type QuestionType, type QuestionValidation, Questionnaire, type QuestionnaireConfig, type QuestionnaireState, type ShowIfCompound, type ShowIfCondition, type ShowIfRule, validateAnswer };

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+type QuestionType = "text" | "number" | "boolean" | "single" | "multi" | "date" | "rating" | "email";
+type ConditionOperator = "eq" | "neq" | "gt" | "lt" | "gte" | "lte" | "includes";
+/** A single condition against one question's response. */
+interface ShowIfCondition {
+    questionId: string;
+    value: unknown;
+    operator?: ConditionOperator;
+}
+/**
+ * Compound condition — nest `and`/`or` arrays for full branching logic.
+ *
+ * @example
+ * // Show only when user has diabetes AND is on insulin
+ * showIf: {
+ *   and: [
+ *     { questionId: 'conditions', value: 'diabetes', operator: 'includes' },
+ *     { questionId: 'on_insulin', value: true },
+ *   ]
+ * }
+ */
+interface ShowIfCompound {
+    and?: ShowIfRule[];
+    or?: ShowIfRule[];
+}
+/** A single condition OR a compound AND/OR tree — fully nestable. */
+type ShowIfRule = ShowIfCondition | ShowIfCompound;
+interface QuestionValidation {
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    regex?: string;
+    message?: string;
+}
+interface QuestionOption {
+    label: string;
+    value: string | number;
+}
+interface Question {
+    id: string;
+    text: string;
+    type: QuestionType;
+    description?: string;
+    required?: boolean;
+    placeholder?: string;
+    options?: QuestionOption[];
+    showIf?: ShowIfRule;
+    validation?: QuestionValidation;
+}
+type DisplayMode = "step" | "all";
+interface QuestionnaireConfig {
+    questions: Question[];
+    mode?: DisplayMode;
+    initialResponses?: Record<string, unknown>;
+}
+interface QuestionnaireState {
+    /** Current question (step mode). In 'all' mode, always the first visible question. */
+    question: Question | null;
+    /** All currently visible questions (after applying showIf conditions). */
+    visibleQuestions: Question[];
+    /** Zero-based index of the current question in the visible questions array. */
+    questionIndex: number;
+    /** Total number of currently visible questions. */
+    totalQuestions: number;
+    /** Progress from 0 to 1 based on how many questions have valid answers. */
+    progress: number;
+    /** All responses keyed by question id. */
+    responses: Record<string, unknown>;
+    /** True when all required visible questions have valid responses. */
+    isComplete: boolean;
+    /** Validation errors keyed by question id. */
+    errors: Record<string, string>;
+    /** Whether the user can navigate to the previous question. */
+    canGoBack: boolean;
+    /** Whether the user can navigate to the next question. */
+    canGoNext: boolean;
+}
+
+declare function validateAnswer(question: Question, value: unknown): string | null;
+type Subscriber = (state: QuestionnaireState) => void;
+declare class Questionnaire {
+    private config;
+    private responses;
+    private questionIndex;
+    private errors;
+    private subscribers;
+    private cachedState;
+    constructor(config: QuestionnaireConfig);
+    private recompute;
+    private notify;
+    getState(): QuestionnaireState;
+    /**
+     * Returns only responses for currently visible questions.
+     * Use this for form submission — avoids sending hidden-branch data to the server.
+     *
+     * `state.responses` retains all answers for back-navigation; this method prunes them.
+     */
+    getSubmittableResponses(): Record<string, unknown>;
+    subscribe(callback: Subscriber): () => void;
+    /**
+     * Answer the current question (step mode).
+     * In `mode: "all"` prefer `answerById()`.
+     */
+    answer(value: unknown): void;
+    /**
+     * Answer any visible question by its id — the right API for `mode: "all"`.
+     * Safe to call in step mode too (allows answering any step by id).
+     */
+    answerById(questionId: string, value: unknown): void;
+    private _setAnswer;
+    /**
+     * Advance to the next step (step mode).
+     * Validates the current required question first; populates `errors` if invalid.
+     */
+    next(): void;
+    /** Go to the previous step. No-op on step 0. */
+    back(): void;
+    /**
+     * Jump to a specific step index (0-based, within visible questions).
+     * Out-of-range indices are silently ignored.
+     */
+    jumpTo(index: number): void;
+    /**
+     * Validate all visible required questions and return a map of errors.
+     * Useful for "submit" gates in `mode: "all"`.
+     */
+    validate(): Record<string, string>;
+    /** Reset all responses and errors, restart from step 0. */
+    reset(): void;
+}
+
+export { type ConditionOperator, type DisplayMode, type Question, type QuestionOption, type QuestionType, type QuestionValidation, Questionnaire, type QuestionnaireConfig, type QuestionnaireState, type ShowIfCompound, type ShowIfCondition, type ShowIfRule, validateAnswer };