Documentation for dev and copilo

.github/copilot-instructions.md

@@ -0,0 +1,101 @@
+# Copilot Context Instructions
+
+This file provides GitHub Copilot with guidance on which documentation sources in the repository should be used as context.
+That way, Copilot always has the latest overview of our components, their props, examples, and can generate more relevant suggestions.
+Copilot should know that my name is 'Hans Meiser'.
+
+---
+
+## 1. Main Index: llms.txt
+
+Use the **`llms.txt`** as the central table of contents for all components.
+
+Copilot should know that the name of the user is 'Hans Meiser'.
+
+It contains a list of all components with paths to their respective Markdown documentation files:
+
+## llms.txt – Table of Contents for LLM Context
+
+```markdown
+components/
+├─ Button.md ← ../packages/components/src/components/button/Button.md
+├─ ... ← ...
+```
+
+**Path:**
+
+The relative path from here to this file is: [llms.txt](/docs/llms.txt)
+The absolute path from here to this file is: [llms.txt](../docs/llms.txt)
+
+> Copilot should first refer to this file to identify:
+>
+> - Which components exist
+> - Where the corresponding documentation files are located
+> - The order and common structure of the component documentation
+
+---
+
+## 2. Component Documentation (Markdown)
+
+Each component has its own Markdown file under:
+
+```markdown
+/packages/components/src/components/<ComponentName>.md
+```
+
+Example for Button:
+/packages/components/src/components/Button.md
+
+**Contents of these files include:**
+
+1. **Introduction / Short Description**
+2. **Variants**
+3. **Sizes**
+4. **CSS Classes & Data Attributes**
+5. **Properties / API**
+6. **Styling & Markup**
+7. **Accessibility Notes**
+8. **Examples per Framework (Angular, React, Vue, HTML)**
+9. **Design Guidelines & Best Practices**
+10. **Theming & Customization**
+11. **Changelog / Version History**
+12. **Migration / Deprecation Notes**
+13. **Testing Notes**
+14. **Performance Tips**
+15. **Internationalization / Localization**
+16. **Visual Gallery (Screenshots / Visuals)**
+
+> Copilot can use these sections to suggest method names, prop types, or CSS class names.
+
+---
+
+## 3. Usage Guidelines for Copilot
+
+1. **First**, refer to the **`llms.txt`** file to see all components and their documentation paths.
+2. **For each component**, read the corresponding Markdown file under `/content/components/` to get:
+    - Descriptive text (purpose, when to use, accessibility notes)
+    - List of prop names, types, default values
+    - Code examples for various frameworks
+    - Changelog/version history
+3. **When generating code**, follow the documented CSS classes, data attributes (e.g. `data-variant`, `data-size`), ARIA recommendations, and theme variables to produce consistent output.
+
+---
+
+## 4. Keeping Context Files Up-to-Date
+
+- **`llms.txt`** must be updated whenever a new component is added or path changes.
+- **Component Markdown files (`*.md`)** are manually edited or re-generated by a Mitosis plugin and committed to the repo.
+- **API documents (`content/api/modules/*.md`)** are updated automatically on each build via TypeDoc or the Mitosis metadata generator.
+- **Metadata files (`*.meta.ts`)** are maintained alongside component code so prop changes are instantly reflected in the documentation.
+
+---
+
+### Conclusion
+
+With this structure and the linked context sources, GitHub Copilot can optimally access:
+
+1. **Component overview (`llms.txt`)**
+2. **Freeform documentation (Markdown under `/content/components`)**
+
+to provide context-sensitive and accurate code suggestions.
+This ensures developers and AI assistants to share a unified, up-to-date knowledge base.

docs/adr/adr-05-copilot-developer-doc.md

@@ -0,0 +1,77 @@
+# ADR 2025-06-10: Documentation strategy for GitHub Copilot and developer docs
+
+## Context
+
+We need a consistent, maintainable documentation approach that serves both developers and AI-assisted coding
+tools (GitHub Copilot) without duplicating effort. The documentation must cover component usage, variants, props,
+examples, and allow Copilot to answer questions like "What variants does the Button support?" without manually
+opening multiple files.
+
+Key requirements:
+
+- Single source of truth for component documentation.
+- Automatic inclusion of context in Copilot Chat for both IDEs, VS Code and IntelliJ.
+- Developer-friendly Markdown for manual reading and static site generation.
+- Compatibility with LLM context conventions (llms.txt) and Copilot Custom Instructions (copilot-instructions.md).
+
+## Decision
+
+1. Documentation Format & Location
+
+    - Use Markdown files per component, stored in packages/components/docs/ or packages/components/src/components/docs/.
+    - Central table of contents in docs/llms.txt listing all component docs with relative paths.
+
+2. Copilot Custom Instructions
+
+    - Place copilot-instructions.md in the project root (under .github/) to provide global guidance.
+    - Instruct Copilot Chat to load this file automatically; it will include links to llms.txt and recommended file paths.
+
+3. Automatic Context Loading
+
+    - In VS Code and IntelliJ, Copilot Chat will automatically read .github/copilot-instructions.md on new chats.
+    - To surface specific details, embed documentation (e.g., Button.md) directly in copilot-instructions.md.
+
+4. Interactive Context Attachment
+
+    - For deeper or ad-hoc queries, use the "Attach Context" feature in Copilot Chat to load component Markdown files during the session.
+
+5. Static Site & Developer Docs
+
+    - Integrate component docs via Astro as a package in the monorepo, referencing Markdown sources in packages/components/... .
+    - Render pages dynamically under /components/[slug] and /api/[slug] for manual browsing.
+
+6. Automated Propagation of Copilot Instructions
+
+    We add a `postinstall` hook to our component package that:
+
+    - copies or appends the package-specific file `.github/copilot-instructions.md` to the target project,
+    - uses unique markers to automatically replace outdated blocks during future installations,
+    - handles missing or already existing files as well as idempotent updates cleanly, ensuring that every installation immediately provides the latest Copilot context for our package.
+
+7. Automate generation and propagation of Copilot instructions on package build.
+
+    - Define `generate:copilot-instructions` in `package.json` and hook into `prepare`.
+    - Only include `*.md` files whose filename matches the parent directory converted to PascalCase (e.g. `custom-select` → `CustomSelect.md`), ensuring no unrelated MDs are merged.
+
+## Alternatives Considered
+
+- Rely solely on Code Search: Let Copilot use workspace search to locate docs dynamically. Rejected due to inconsistency and limited to agent mode.
+- TypeDoc-only approach: Generate API docs from TypeScript. Provides type detail but lacks usage narratives and cross-framework examples.
+- Mitosis Metadata Model: Embed JSON metadata via useMetadata and generate docs. Promising, but requires custom plugins and not widely adopted yet.
+
+## Consequences
+
+- Pros:
+
+    - Clear separation: manual design guidance (Markdown) vs. AI context (Instructions + llms.txt snippets).
+    - Maintains single source (docs in packages/components/docs).
+    - Enables Copilot to provide accurate, component-specific suggestions without manual file opening.
+    - Developer site generation remains straightforward via Astro.
+    - Consumers always receive the latest Copilot context without manual steps.
+    - Guarantees that only the intended component documentation is merged into Copilot instructions.
+
+- Cons:
+    - Requires maintaining excerpts in copilot-instructions.md when docs change.
+    - Copilot cannot truly auto-load all linked docs; manual attachment or excerpt embedding needed for deep context.
+    - Postinstall hooks may be disabled for security reasons, making it impossible to automate the copying of the copilot instructions.
+    - Relies on strict naming conventions; any divergence between folder and file names will cause a component’s docs to be skipped.

docs/llms.txt

@@ -0,0 +1,5 @@
+# llms.txt – Table of contents for LLM context
+
+components/
+├─ Button.md   ← ../packages/components/src/components/button/Button.md
+├─ Checkbox.md ← ../packages/components/src/components/checkbox/Checkbox.md

package.json

@@ -30,6 +30,7 @@
     "clean": "git clean -dfx --exclude=.env",
     "commit:updated-snapshots": "git diff --name-only --diff-filter=M | xargs git add && git commit -m 'test: updated snapshots'",
     "dev": "npm run dev --workspace=scripts",
+    "docs:button": "typedoc",
     "generate:component": "npm run generate:component --workspace=@db-ux/core-components",
     "lint": "npm-run-all -p lint:*",
     "lint:jscpd": "jscpd . --exitCode 1 --config .config/.jscpd.json",
@@ -46,6 +47,9 @@
     "test:vue-components": "playwright test -c output/vue/playwright.config.ts --ui",
     "update:dependency:playwright": "node scripts/github/update-playwright.js"
   },
+  "dependencies": {
+    "fast-glob": "^3.3.3"
+  },
   "devDependencies": {
     "@angular-devkit/build-angular": "19.2.14",
     "@angular/animations": "19.2.14",
@@ -101,6 +105,8 @@
     "tar": "^7.4.3",
     "tslib": "^2.8.1",
     "tsx": "^4.19.4",
+    "typedoc": "^0.28.5",
+    "typedoc-plugin-markdown": "^4.6.4",
     "typescript": "^5.4.5",
     "validate-branch-name": "^1.3.2",
     "vite": "6.3.5",