Initial commit

Author: ericof

.claude/.gitkeep

@@ -0,0 +1,35 @@
+
+# EditorConfig Configurtaion file, for more details see:
+# https://EditorConfig.org
+# EditorConfig is a convention description, that could be interpreted
+# by multiple editors to enforce common coding conventions for specific
+# file types
+
+# top-most EditorConfig file:
+# Will ignore other EditorConfig files in Home directory or upper tree level.
+root = true
+
+
+[*]  # For All Files
+# Unix-style newlines with a newline ending every file
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+# Set default charset
+charset = utf-8
+# Indent style default
+indent_style = space
+
+[*.{py,cfg,ini}]
+# 4 space indentation
+indent_size = 4
+
+[*.{html,dtml,pt,zpt,xml,zcml,js,json,ts,less,scss,css,sass,toml,yml,yaml}]
+# 2 space indentation
+indent_size = 2
+
+[{Makefile,.gitmodules}]
+# Tab indentation (no size specified, but view as 4 spaces)
+indent_style = tab
+indent_size = unset
+tab_width = unset

.editorconfig

@@ -0,0 +1 @@
+* @ericof

.github/CODEOWNERS

@@ -0,0 +1,169 @@
+---
+applyTo: "docs/src/**/*.md"
+---
+# Documentation standards
+
+This codebase is a library that helps developers to build schema-driven form wizards for the terminal
+
+ALWAYS use `TUI Forms` as the friendly name of the package and `tui-forms` when refering to the package codebase.
+
+## 1. Audience and scope
+
+- This library is intended for Python developers building terminal applications or command line utilities.
+- About the reader:
+  - Could be categorized as:
+    - **End User**: Python developer willing to use this library in their own projects.
+    - **Contributor**: Also a Python developer, probably also an End User, but someone willing to contribute to this library by fixing issues, implementing new features, and writing documentation.
+  - Assume they know: Python development terms, Python 3.12+
+  - Do NOT assume they know: internal architecture decisions, the history of the project, or even other libraries providing the same features.
+- Full documentation lives at: https://collective.github.io/tui-forms
+
+---
+
+## 2. Documentation structure (Diátaxis)
+
+All documentation must fit one of these four types. Never mix types in the same file.
+
+| Type | Purpose | Answers |
+|---|---|---|
+| **Tutorial** | Learning-oriented, step-by-step | "How do I get started?" |
+| **How-to guide** | Task-oriented, goal-focused | "How do I accomplish X?" |
+| **Reference** | Information-oriented, API/config | "What does parameter X do?" |
+| **Explanation** | Understanding-oriented, concepts | "Why does it work this way?" |
+
+When drafting a new file, STATE which type it is at the top of your working notes before writing.
+
+---
+
+## 3. File metadata (REQUIRED on every file)
+
+Every `.md` file must begin with a MyST metadata block. Use this template and fill in accurate values — do not copy the placeholder text verbatim into the output:
+
+```markdown
+---
+myst:
+  html_meta:
+    "description": "[PLACEHOLDER: one sentence, plain English, no marketing language]"
+    "property=og:description": "[PLACEHOLDER: same as description above]"
+    "property=og:title": "[PLACEHOLDER: page title, matches the H1 heading below]"
+    "keywords": "[PLACEHOLDER: comma-separated, include library name, relevant concepts]"
+---
+```
+
+Rules:
+- `description` must be a single sentence under 160 characters.
+- `keywords` must include `tui-forms` as the first keyword.
+- The `og:title` must exactly match the H1 heading of the page.
+- NEVER copy example metadata from another page without updating all four fields.
+
+---
+
+## 4. Toolchain
+
+- **Documentation framework**: Sphinx with MyST-Parser (Markdown)
+- **Setup environment**: `make install`
+- **Build command**: `make docs-html`
+- **Live preview**: `make docs-livehtml`
+- **Output directory**: `docs/_build/html`
+- **Hosting**: `GitHub Pages`
+
+Before suggesting any Sphinx extension or MyST feature, verify it is listed in `docs/src/conf.py`. Do not assume extensions are available.
+
+---
+
+## 5. Writing standards (Vale-enforced)
+
+Vale is configured for **American English** with the following style guides active:
+- Microsoft
+
+Vale runs via: `make docs-vale`
+
+Rules that Vale does NOT catch but must still be followed:
+
+- Use second-person voice ("you", not "the user" or "one").
+- Use active voice. Passive voice is allowed only when the actor is genuinely unknown.
+- Use present tense ("returns a string", not "will return a string").
+- Sentence case for all headings ("Getting started", not "Getting Started"). Exception: proper nouns and the library name.
+- One sentence per line in the source Markdown (makes diffs readable).
+- No filler phrases: "simply", "just", "easily", "obviously", "of course".
+- Spell out acronyms on first use per page, even common ones.
+
+---
+
+## 6. Code examples
+
+- ALL code examples must be tested and working against the current version.
+- Use `tui_forms` as the import in all examples.
+- Show the minimal working example first, then add complexity.
+- Every code block must have a language tag:
+  ````markdown
+  ```python
+  ```
+  ````
+- If an example requires setup not shown inline, reference the relevant how-to guide explicitly.
+- NEVER fabricate API behaviour. If unsure whether a method exists or behaves a certain way, read the source at `src/tui_forms` before writing.
+
+---
+
+## 7. MyST-specific syntax
+
+Use MyST directives correctly. Prefer these patterns:
+
+**Notes and warnings:**
+```markdown
+:::{note}
+Use notes sparingly — only for information the reader would otherwise miss.
+:::
+
+:::{warning}
+Reserve warnings for actions that could cause data loss or security issues.
+:::
+```
+
+**Cross-references** (always use labels, never bare URLs for internal links):
+```markdown
+{doc}`/path/to/page`
+{ref}`label-name`
+{py:func}`yourlibrary.module.function`
+```
+
+**Do not use** raw HTML unless there is no MyST equivalent.
+
+---
+
+## 8. What to verify before writing
+
+Before drafting any documentation:
+
+1. Read the relevant source files in `src/tui_forms`.
+2. Check whether existing documentation already covers the topic (`docs/src`).
+3. Run the build to confirm there are no pre-existing errors: `make docs-html`.
+
+FORBIDDEN: "I think this method does...", "It should...", "Probably..."
+REQUIRED: "According to `[file:line]`...", "The source shows..."
+
+If the behaviour is not clear from the source, STATE: "I cannot confirm this from the source code — please verify."
+
+---
+
+## 9. Definition of done
+
+A documentation task is complete only when:
+
+- [ ] Vale passes with zero errors: `make docs-vale`
+- [ ] Sphinx builds with zero warnings: `make docs-html`
+- [ ] All internal cross-references resolve.
+- [ ] All code examples have been run and produce the stated output.
+- [ ] Metadata block is present and accurate on every new or modified file.
+- [ ] The page fits exactly one Diátaxis type.
+
+"The page renders" is not done. "Vale passes" is not done on its own. All six must be true.
+
+---
+
+## 10. What not to do
+
+- NEVER mix tutorial and reference content in the same page.
+- NEVER use the word "simply" or "just" (Vale will catch this, but be proactive).
+- NEVER document behaviour you have not verified in the source.
+- NEVER copy metadata from another page without updating all fields.

.github/instructions/docs.instructions.md

@@ -0,0 +1,61 @@
+---
+applyTo: "README.md"
+---
+# README file standards
+
+## 1. Audience and scope
+
+- This library is intended for Python developers building terminal applications or command line utilities.
+- The README.md file is going to be the first contact the reader has with this project:
+  - Will be viewed on GitHub
+  - Will be viewed also on PyPI
+- The file must:
+  - Start with a short tagline and a brief project description.
+  - Describe the features with enough detail so the reader understands what each feature does:
+    - ✅ (good bullet point wording): `- Different renderers using other Python libraries like rich`
+    - ❌ (too vague): `- Renderers`
+    - Review the code if necessary to explain features accurately.
+  - Include a minimal usage/code example showing how to define a JSONSchema and render a form.
+  - Provide installation instructions for end users (using `pip`, `poetry`, and `uv`).
+  - Provide installation instructions for developers willing to contribute to this project.
+  - End with a license section.
+- About the reader:
+  - Could be categorized as:
+    - **End User**: Python developer willing to use this library in their own projects.
+    - **Contributor**: Also a Python developer, probably also an End User, but someone willing to contribute to this library by fixing issues, implementing new features, and writing documentation.
+  - Assume they know: Python development terms, Python 3.12+
+  - Do NOT assume they know: internal architecture decisions, the history of the project, or even other libraries providing the same features.
+- Full documentation lives at: https://collective.github.io/tui-forms
+
+## 2. Suggested README structure
+
+Use this section order:
+
+1. Badges (CI status, PyPI version, license)
+2. Project name and tagline
+3. Short description (2–4 sentences)
+4. Features (bulleted list with enough detail)
+5. Usage (minimal code example)
+6. Installation (End User)
+7. Contributing (Contributor setup)
+8. License
+
+## 3. Recommendations
+
+- ALWAYS use `TUI Forms` as the friendly name of the package and `tui-forms` when refering to the package codebase.
+- ALWAYS use emojis in section titles for a friendly tone.
+- ALWAYS use second person ("you") when addressing the reader.
+- End User:
+  - Provide installation instructions on how to add this package to their own projects using `pip`, `poetry`, and `uv`.
+  - Refer them to the full documentation for usage and how to integrate with their own project.
+- Contributor:
+  - ALWAYS recommend using `make` commands. The key targets are:
+    - `make install` — set up the development environment
+    - `make format` — format the codebase
+    - `make lint` — run the linter
+    - `make lint-mypy` — check type hints
+    - `make test` — run all tests
+    - `make test-coverage` — run tests with coverage report
+    - `make docs-html` — build the HTML documentation
+    - `make docs-livehtml` — build and serve documentation locally
+  - NEVER recommend using `pip install`, `uv add`, or `uv pip` directly.

.github/instructions/readme.instructions.md

@@ -0,0 +1,34 @@
+name: Changelog check
+on:
+  pull_request:
+    types:
+      - assigned
+      - opened
+      - synchronize
+      - reopened
+      - labeled
+      - unlabeled
+    branches:
+      - main
+
+env:
+  python-version: 3.13
+
+jobs:
+  changelog:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Fetch all history
+          fetch-depth: 0
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ env.python-version }}
+
+      - name: Check for presence of a Change Log fragment
+        run: |
+          git fetch --no-tags origin ${{ github.base_ref }}
+          uvx towncrier check  --compare-with origin/${{ github.base_ref }} --config pyproject.toml --dir .

.github/workflows/changelog.yml

@@ -0,0 +1,69 @@
+name: 'Compute Config variables'
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: "3.12"
+    outputs:
+      backend:
+        description: "Flag reporting if we should run the code jobs"
+        value: ${{ jobs.config.outputs.backend }}
+      docs:
+        description: "Flag reporting if we should run the docs jobs"
+        value: ${{ jobs.config.outputs.docs }}
+      base-tag:
+        description: "Base tag to be used when creating container images"
+        value: ${{ jobs.config.outputs.base-tag }}
+      python-version:
+        description: "Python version to be used"
+        value: ${{ inputs.python-version }}
+      version-pyroma:
+        description: "Pyroma version"
+        value: "latest"
+      version-ruff:
+        description: "Ruff version"
+        value: "latest"
+      version-check-python:
+        description: "Check Python version"
+        value: "latest"
+
+jobs:
+  config:
+    runs-on: ubuntu-latest
+    outputs:
+      backend: ${{ steps.filter.outputs.backend }}
+      docs: ${{ steps.filter.outputs.docs }}
+      base-tag: ${{ steps.vars.outputs.BASE_TAG }}
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Compute several vars needed for the CI
+        id: vars
+        run: |
+          echo "base-tag=sha-$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - uses: dorny/paths-filter@v3.0.2
+        id: filter
+        with:
+          filters: |
+            backend:
+              - '**'
+              - '.github/workflows/config.yml'
+              - '.github/workflows/main.yml'
+            docs:
+              - 'docs/**'
+              - '.vale'
+              - '.github/workflows/docs.yml'
+
+      - name: Test vars
+        run: |
+          echo "base-tag: ${{ steps.vars.outputs.base-tag }}"
+          echo 'event-name: ${{ github.event_name }}'
+          echo "ref-name: ${{ github.ref_name }}"
+          echo 'Paths - code: ${{ steps.filter.outputs.backend }}'
+          echo 'Paths - docs: ${{ steps.filter.outputs.docs }}'