From 74f97a3a28eeb6f1ae284b84d3e28a7e93e8f99c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Bokisch?= Date: Wed, 25 Mar 2026 12:36:56 +0100 Subject: [PATCH 1/2] chore: modernize tooling, deps, and CI to match pyreon ecosystem - Upgrade TypeScript to ^6.0.2 (aligned with pyreon/fundamentals/zero) - Update tsconfig target to ES2024, add ignoreDeprecations for baseUrl - Pin all CI actions by SHA (checkout v6.0.2, setup-bun v2.2.0, codeql v3.32.6) - Add timeouts, dependency-review, and CodeQL to ci.yml - Refactor deploy.yml to reuse ci.yml via workflow_call - Add fumadocs/react/tailwind/types groups to dependabot - Bump biome schema to 2.4.8 - Fix PropTable crash on undefined props - Add CLAUDE.md for AI-assisted development context Co-Authored-By: Claude Opus 4.6 (1M context) --- .github/dependabot.yml | 18 +++- .github/workflows/ci.yml | 105 +++++++++++------------- .github/workflows/codeql.yml | 22 ++--- .github/workflows/dependency-update.yml | 12 ++- .github/workflows/deploy.yml | 37 ++------- CLAUDE.md | 76 +++++++++++++++++ biome.json | 2 +- bun.lock | 32 ++++---- package.json | 2 +- src/components/prop-table.tsx | 4 +- tsconfig.json | 3 +- 11 files changed, 189 insertions(+), 124 deletions(-) create mode 100644 CLAUDE.md diff --git a/.github/dependabot.yml b/.github/dependabot.yml index fb3fdb4..1d3a934 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -12,7 +12,22 @@ updates: - dependencies - automated groups: - # Group minor/patch updates together + fumadocs: + patterns: + - "fumadocs-*" + react: + patterns: + - "react" + - "react-dom" + - "@types/react" + - "@types/react-dom" + tailwind: + patterns: + - "tailwindcss" + - "@tailwindcss/*" + types: + patterns: + - "@types/*" production: dependency-type: production update-types: @@ -23,7 +38,6 @@ updates: update-types: - minor - patch - # Auto-merge patch updates commit-message: prefix: "chore(deps):" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cd98e85..7178f0a 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -3,93 +3,88 @@ name: CI on: pull_request: branches: [main] - push: - branches: [main] + # Allow reuse from deploy workflow + workflow_call: concurrency: - group: ci-${{ github.ref }} + group: ci-${{ github.head_ref || github.ref }} cancel-in-progress: true permissions: contents: read jobs: - typecheck: - name: Typecheck + lint: + name: Lint & Format runs-on: ubuntu-latest + timeout-minutes: 5 steps: - - uses: actions/checkout@v4 - - - uses: oven-sh/setup-bun@v2 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: latest + - run: bun install --frozen-lockfile + - run: bun run lint - - name: Install dependencies - run: bun install --frozen-lockfile - - - name: Run typecheck - run: bun run typecheck - - lint: - name: Lint + typecheck: + name: Typecheck runs-on: ubuntu-latest + timeout-minutes: 5 steps: - - uses: actions/checkout@v4 - - - uses: oven-sh/setup-bun@v2 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: latest - - - name: Install dependencies - run: bun install --frozen-lockfile - - - name: Run Biome - run: bun run lint + - run: bun install --frozen-lockfile + - run: bun run typecheck build: name: Build runs-on: ubuntu-latest - needs: [typecheck, lint] + timeout-minutes: 10 + needs: [lint, typecheck] steps: - - uses: actions/checkout@v4 - - - uses: oven-sh/setup-bun@v2 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: latest - - - name: Install dependencies - run: bun install --frozen-lockfile - + - run: bun install --frozen-lockfile - name: Build static site run: bun run build - - name: Upload build artifact if: github.ref == 'refs/heads/main' - uses: actions/upload-pages-artifact@v3 + uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1 with: path: out - security: - name: Security audit + dependency-review: + name: Dependency Review runs-on: ubuntu-latest + timeout-minutes: 5 + if: github.event_name == 'pull_request' steps: - - uses: actions/checkout@v4 - - - uses: oven-sh/setup-bun@v2 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Review dependency changes + uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0 with: - bun-version: latest + fail-on-severity: high + deny-licenses: GPL-3.0, AGPL-3.0 - - name: Install dependencies - run: bun install --frozen-lockfile - - - name: Audit dependencies - run: bun pm audit || true - - - name: Check for known vulnerabilities in lockfile - run: | - # Fail on critical/high vulnerabilities - bun pm audit 2>&1 | tee audit-output.txt - if grep -qiE '(critical|high)' audit-output.txt; then - echo "::error::Critical or high severity vulnerabilities found" - exit 1 - fi + codeql: + name: CodeQL Analysis + runs-on: ubuntu-latest + timeout-minutes: 10 + permissions: + contents: read + security-events: write + steps: + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + - name: Initialize CodeQL + uses: github/codeql-action/init@e03543dad62555ecf6606aabe9724fd07e1cd632 # v3.32.6 + with: + languages: javascript-typescript + queries: security-and-quality + - name: Run CodeQL analysis + uses: github/codeql-action/analyze@e03543dad62555ecf6606aabe9724fd07e1cd632 # v3.32.6 + with: + category: /language:javascript-typescript diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index e7334ac..7c4516b 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -1,10 +1,6 @@ name: CodeQL Security Analysis on: - push: - branches: [main] - pull_request: - branches: [main] schedule: # Every Wednesday at 04:00 UTC - cron: "0 4 * * 3" @@ -17,24 +13,20 @@ jobs: analyze: name: Analyze runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - language: [javascript-typescript] - + timeout-minutes: 10 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: Initialize CodeQL - uses: github/codeql-action/init@v3 + uses: github/codeql-action/init@e03543dad62555ecf6606aabe9724fd07e1cd632 # v3.32.6 with: - languages: ${{ matrix.language }} + languages: javascript-typescript queries: security-and-quality - name: Autobuild - uses: github/codeql-action/autobuild@v3 + uses: github/codeql-action/autobuild@e03543dad62555ecf6606aabe9724fd07e1cd632 # v3.32.6 - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v3 + uses: github/codeql-action/analyze@e03543dad62555ecf6606aabe9724fd07e1cd632 # v3.32.6 with: - category: "/language:${{ matrix.language }}" + category: /language:javascript-typescript diff --git a/.github/workflows/dependency-update.yml b/.github/workflows/dependency-update.yml index 553b333..b56e672 100644 --- a/.github/workflows/dependency-update.yml +++ b/.github/workflows/dependency-update.yml @@ -14,10 +14,11 @@ jobs: update-dependencies: name: Check for updates runs-on: ubuntu-latest + timeout-minutes: 10 steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - - uses: oven-sh/setup-bun@v2 + - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0 with: bun-version: latest @@ -30,11 +31,14 @@ jobs: - name: Typecheck with updated deps run: bun run typecheck + - name: Lint with updated deps + run: bun run lint + - name: Build with updated deps run: bun run build - name: Create PR if changes exist - uses: peter-evans/create-pull-request@v7 + uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8 with: token: ${{ secrets.GITHUB_TOKEN }} commit-message: "chore(deps): update dependencies" @@ -43,7 +47,7 @@ jobs: Automated weekly dependency update. This PR updates all dependencies to their latest compatible versions. - The build and typecheck passed with the updated dependencies. + Typecheck, lint, and build passed with the updated dependencies. --- _Generated by the dependency-update workflow._ diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 06e2b62..b6a4d46 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -15,41 +15,22 @@ permissions: id-token: write jobs: - build: - name: Build - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - uses: oven-sh/setup-bun@v2 - with: - bun-version: latest - - - name: Install dependencies - run: bun install --frozen-lockfile - - - name: Typecheck - run: bun run typecheck - - - name: Lint - run: bun run lint - - - name: Build static site - run: bun run build - - - name: Upload Pages artifact - uses: actions/upload-pages-artifact@v3 - with: - path: out + ci: + name: CI + uses: ./.github/workflows/ci.yml + permissions: + contents: read + security-events: write deploy: name: Deploy runs-on: ubuntu-latest - needs: build + timeout-minutes: 5 + needs: ci environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4.0.5 diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..6af0f83 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,76 @@ +# @pyreon/docs + +Documentation site for the Pyreon UI framework ecosystem. + +## Stack + +- **Framework**: Next.js 16 (App Router, static export to `out/`) +- **Docs engine**: Fumadocs (fumadocs-core, fumadocs-ui, fumadocs-mdx) +- **Styling**: Tailwind CSS v4 + fumadocs-ui preset +- **Linting**: Biome (extends `@vitus-labs/tools-lint/biome`) +- **TypeScript**: 6.x with strict mode +- **Package manager**: Bun +- **Deployment**: GitHub Pages via GitHub Actions + +## Project structure + +``` +src/ + app/ + (home)/page.tsx — Landing page (hero, features, package cards) + docs/layout.tsx — Docs sidebar layout (fumadocs DocsLayout) + docs/[[...slug]]/page.tsx — Dynamic MDX page renderer + layout.tsx — Root layout (RootProvider, static search) + global.css — Tailwind imports + custom hero/card styles + components/ — Custom MDX components (APICard, PackageBadge, PropTable, CompatMatrix, Since) + lib/ + source.ts — Fumadocs source loader + layout.shared.tsx — Nav/link config shared between layouts + +content/docs/ — MDX documentation pages (one folder per package) +source.config.ts — Fumadocs MDX config (remarkInstall plugin) +mdx-components.tsx — MDX component registry +``` + +## Commands + +```bash +bun run dev # Start dev server +bun run build # Static export to out/ +bun run typecheck # tsc --noEmit +bun run lint # biome check . +bun run lint:fix # biome check . --write +bun run format # biome format . --write +bun run check # typecheck + lint + build +``` + +## Content authoring + +- Each package has a folder under `content/docs//` with `index.mdx` and optional `meta.json` +- MDX files use fumadocs frontmatter (`title`, `description`) +- Custom components available in MDX: `APICard`, `PackageBadge`, `PropTable`, `CompatMatrix`, `Since` +- Install blocks use `remarkInstall` plugin — write ```` ```package-install ```` +- Navigation tree is driven by `meta.json` files (fumadocs convention) + +## Custom MDX components + +- **APICard** — API item card with type badge (fn, C, H, T, K, P, Cx) and optional signature +- **PackageBadge** — Package name/version badge with status indicator (stable/beta/alpha/deprecated) +- **PropTable** — Props documentation table with columns: Prop, Type, Default, Description +- **CompatMatrix** — Framework compatibility table with support levels (full/partial/none) +- **Since** — Version badge (e.g. "v1.2.0+") + +## CI/CD + +- `ci.yml` — PR checks: lint, typecheck, build, dependency-review, CodeQL +- `deploy.yml` — Push to main: runs CI, then deploys `out/` to GitHub Pages +- `dependency-update.yml` — Weekly Monday: `bun update`, typecheck, lint, build, auto-PR +- `codeql.yml` — Weekly Wednesday: standalone security scan +- Dependabot groups: fumadocs, react, tailwind, types, GitHub Actions + +## Conventions + +- Static export (`output: 'export'`) — no server runtime +- All GitHub Actions pinned by SHA with version comment +- Biome extends `@vitus-labs/tools-lint/biome` (shared across Pyreon repos) +- No tests (static docs site) — quality gates are typecheck + lint + build diff --git a/biome.json b/biome.json index b2f4c4e..f2e15eb 100644 --- a/biome.json +++ b/biome.json @@ -1,5 +1,5 @@ { - "$schema": "https://biomejs.dev/schemas/2.4.6/schema.json", + "$schema": "https://biomejs.dev/schemas/2.4.8/schema.json", "extends": ["@vitus-labs/tools-lint/biome"], "files": { "includes": [ diff --git a/bun.lock b/bun.lock index 87c0c93..2f4d3d4 100644 --- a/bun.lock +++ b/bun.lock @@ -5,23 +5,23 @@ "": { "name": "@pyreon/docs", "dependencies": { - "fumadocs-core": "latest", - "fumadocs-mdx": "latest", - "fumadocs-ui": "latest", - "next": "latest", - "react": "latest", - "react-dom": "latest", + "fumadocs-core": "^16.7.4", + "fumadocs-mdx": "^14.2.11", + "fumadocs-ui": "^16.7.4", + "next": "^16.2.1", + "react": "^19.2.4", + "react-dom": "^19.2.4", }, "devDependencies": { - "@tailwindcss/postcss": "latest", - "@types/mdx": "latest", - "@types/node": "latest", - "@types/react": "latest", - "@types/react-dom": "latest", - "@vitus-labs/tools-lint": "latest", - "fumadocs-docgen": "latest", - "tailwindcss": "latest", - "typescript": "latest", + "@tailwindcss/postcss": "^4.2.2", + "@types/mdx": "^2.0.13", + "@types/node": "^25.5.0", + "@types/react": "^19.2.14", + "@types/react-dom": "^19.2.3", + "@vitus-labs/tools-lint": "^1.15.4", + "fumadocs-docgen": "^3.0.8", + "tailwindcss": "^4.2.2", + "typescript": "^6.0.2", }, }, }, @@ -796,7 +796,7 @@ "tslib": ["tslib@2.8.1", "", {}, "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w=="], - "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="], + "typescript": ["typescript@6.0.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-bGdAIrZ0wiGDo5l8c++HWtbaNCWTS4UTv7RaTH/ThVIgjkveJt83m74bBHMJkuCbslY8ixgLBVZJIOiQlQTjfQ=="], "undici-types": ["undici-types@7.18.2", "", {}, "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w=="], diff --git a/package.json b/package.json index 7dfd4e0..c0b9939 100644 --- a/package.json +++ b/package.json @@ -35,6 +35,6 @@ "@vitus-labs/tools-lint": "^1.15.4", "fumadocs-docgen": "^3.0.8", "tailwindcss": "^4.2.2", - "typescript": "^5.9.3" + "typescript": "^6.0.2" } } diff --git a/src/components/prop-table.tsx b/src/components/prop-table.tsx index 8d24d9f..d8f3589 100644 --- a/src/components/prop-table.tsx +++ b/src/components/prop-table.tsx @@ -13,7 +13,9 @@ interface PropTableProps { props: Prop[] } -export function PropTable({ title, props }: PropTableProps): ReactNode { +export function PropTable({ title, props = [] }: PropTableProps): ReactNode { + if (!props || props.length === 0) return null + return (
{title && ( diff --git a/tsconfig.json b/tsconfig.json index 922b926..e915135 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -1,6 +1,6 @@ { "compilerOptions": { - "target": "ES2017", + "target": "ES2024", "lib": ["dom", "dom.iterable", "esnext"], "allowJs": true, "skipLibCheck": true, @@ -14,6 +14,7 @@ "jsx": "react-jsx", "incremental": true, "baseUrl": ".", + "ignoreDeprecations": "6.0", "plugins": [{ "name": "next" }], "paths": { "@/*": ["./src/*"], From 52dd6203198e46fa7a61e5b4ca57b4d9706a810d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?V=C3=ADt=20Bokisch?= Date: Wed, 25 Mar 2026 13:32:24 +0100 Subject: [PATCH 2/2] docs: add 11 missing package pages, complete sidebar and index MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add docs for: kinetic, attrs, rocketstyle, ui-core, connector-document, document-primitives, cli, devtools, meta, create-zero - Add meta.json to 10 existing folders missing them (charts, code, document, feature, flow, hotkeys, machine, permissions, storage, typescript) - Update sidebar navigation with all packages organized into sections: Core Framework, Compatibility, State & Data, Meta-Framework, UI System, Ecosystem, Developer Tools - Update docs index.mdx with complete package tables (50+ packages) - Update homepage: package count 27→50+, add State & Data and Ecosystem sections with new package cards Co-Authored-By: Claude Opus 4.6 (1M context) --- content/docs/attrs/index.mdx | 101 +++++++++++ content/docs/attrs/meta.json | 5 + content/docs/charts/meta.json | 5 + content/docs/cli/index.mdx | 55 ++++++ content/docs/cli/meta.json | 5 + content/docs/code/meta.json | 5 + content/docs/connector-document/index.mdx | 90 ++++++++++ content/docs/connector-document/meta.json | 5 + content/docs/create-zero/index.mdx | 54 ++++++ content/docs/create-zero/meta.json | 5 + content/docs/devtools/index.mdx | 44 +++++ content/docs/devtools/meta.json | 5 + content/docs/document-primitives/index.mdx | 106 +++++++++++ content/docs/document-primitives/meta.json | 5 + content/docs/document/meta.json | 5 + content/docs/feature/meta.json | 5 + content/docs/flow/meta.json | 5 + content/docs/hotkeys/meta.json | 5 + content/docs/index.mdx | 33 ++++ content/docs/kinetic/index.mdx | 198 +++++++++++++++++++++ content/docs/kinetic/meta.json | 5 + content/docs/machine/meta.json | 5 + content/docs/meta.json | 23 ++- content/docs/meta/index.mdx | 38 ++++ content/docs/meta/meta.json | 5 + content/docs/permissions/meta.json | 5 + content/docs/rocketstyle/index.mdx | 147 +++++++++++++++ content/docs/rocketstyle/meta.json | 5 + content/docs/storage/meta.json | 5 + content/docs/typescript/meta.json | 5 + content/docs/ui-core/index.mdx | 146 +++++++++++++++ content/docs/ui-core/meta.json | 5 + src/app/(home)/page.tsx | 109 +++++++++++- 33 files changed, 1237 insertions(+), 7 deletions(-) create mode 100644 content/docs/attrs/index.mdx create mode 100644 content/docs/attrs/meta.json create mode 100644 content/docs/charts/meta.json create mode 100644 content/docs/cli/index.mdx create mode 100644 content/docs/cli/meta.json create mode 100644 content/docs/code/meta.json create mode 100644 content/docs/connector-document/index.mdx create mode 100644 content/docs/connector-document/meta.json create mode 100644 content/docs/create-zero/index.mdx create mode 100644 content/docs/create-zero/meta.json create mode 100644 content/docs/devtools/index.mdx create mode 100644 content/docs/devtools/meta.json create mode 100644 content/docs/document-primitives/index.mdx create mode 100644 content/docs/document-primitives/meta.json create mode 100644 content/docs/document/meta.json create mode 100644 content/docs/feature/meta.json create mode 100644 content/docs/flow/meta.json create mode 100644 content/docs/hotkeys/meta.json create mode 100644 content/docs/kinetic/index.mdx create mode 100644 content/docs/kinetic/meta.json create mode 100644 content/docs/machine/meta.json create mode 100644 content/docs/meta/index.mdx create mode 100644 content/docs/meta/meta.json create mode 100644 content/docs/permissions/meta.json create mode 100644 content/docs/rocketstyle/index.mdx create mode 100644 content/docs/rocketstyle/meta.json create mode 100644 content/docs/storage/meta.json create mode 100644 content/docs/typescript/meta.json create mode 100644 content/docs/ui-core/index.mdx create mode 100644 content/docs/ui-core/meta.json diff --git a/content/docs/attrs/index.mdx b/content/docs/attrs/index.mdx new file mode 100644 index 0000000..608b1ab --- /dev/null +++ b/content/docs/attrs/index.mdx @@ -0,0 +1,101 @@ +--- +title: Attrs +description: Chainable component factory for composing default props, styles, and behaviors on Pyreon components. +--- + +`@pyreon/attrs` provides a chainable component factory (`attrs()`) that lets you compose default props, styles, and behaviors on any Pyreon component. Each `.attrs()` call returns a new component with the merged defaults. + + + +## Installation + +```package-install +@pyreon/attrs +``` + +## Overview + +The `attrs` function wraps a base component and lets you layer default props onto it through a chainable `.attrs()` API. Each call returns a new component -- the original is never mutated. At render time, all layered defaults are merged with the props passed at the call site, with call-site props taking precedence. + +This is useful for building design-system components where you want to pre-configure common prop combinations without creating one-off wrapper components. + +## Quick Start + +```tsx +import attrs from '@pyreon/attrs' + +// Start with a base component +const BaseButton = (props) => + +// Layer defaults +const Button = attrs(BaseButton) + .attrs({ type: 'button' }) + +const PrimaryButton = Button + .attrs({ class: 'btn-primary', role: 'button' }) + +const LargePrimaryButton = PrimaryButton + .attrs({ class: 'btn-primary btn-lg' }) + +// Use like any component -- call-site props override defaults +Submit +``` + +## Dynamic Defaults + +Pass a function to `.attrs()` to compute defaults based on incoming props: + +```tsx +const Input = attrs(BaseInput) + .attrs((props) => ({ + 'aria-invalid': props.error ? 'true' : undefined, + class: props.error ? 'input-error' : 'input', + })) +``` + +## Chaining + +Each `.attrs()` call creates a new component in the chain. Defaults are merged in order -- later calls override earlier ones for the same prop: + +```tsx +const Base = attrs(Component) + .attrs({ variant: 'default', size: 'md' }) + +const Small = Base + .attrs({ size: 'sm' }) +// Effective defaults: { variant: 'default', size: 'sm' } + +const SmallPrimary = Small + .attrs({ variant: 'primary' }) +// Effective defaults: { variant: 'primary', size: 'sm' } +``` + +## Integration with Rocketstyle + +`@pyreon/attrs` is used internally by `@pyreon/rocketstyle` to build its multi-dimensional style composition. You can also use it standalone for simpler prop-composition needs. + +## API Reference + +| Export | Type | Description | +|---|---|---| +| `attrs` | Function | Wraps a component and returns a chainable attrs builder | +| `isAttrsComponent` | Function | Type guard to check if a value is an attrs-wrapped component | + +## Types + +| Type | Description | +|---|---| +| `Attrs` | The attrs builder interface with the `.attrs()` method | +| `AttrsComponent` | A component produced by the attrs chain | +| `AttrsCb` | Callback signature for dynamic attrs: `(props) => Partial` | +| `ConfigAttrs` | Internal configuration type for attrs layers | + +## Key Features + +- Chainable `.attrs()` API for layering default props +- Static object or dynamic function defaults +- Immutable -- each `.attrs()` call returns a new component +- Call-site props always override defaults +- Works with any Pyreon component +- Used internally by `@pyreon/rocketstyle` for style composition +- Full TypeScript support with inferred prop types diff --git a/content/docs/attrs/meta.json b/content/docs/attrs/meta.json new file mode 100644 index 0000000..906ffc4 --- /dev/null +++ b/content/docs/attrs/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/attrs", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/charts/meta.json b/content/docs/charts/meta.json new file mode 100644 index 0000000..52ec5f5 --- /dev/null +++ b/content/docs/charts/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/charts", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/cli/index.mdx b/content/docs/cli/index.mdx new file mode 100644 index 0000000..ef7ce90 --- /dev/null +++ b/content/docs/cli/index.mdx @@ -0,0 +1,55 @@ +--- +title: "@pyreon/cli" +description: CLI tools for Pyreon — doctor, generate, and context commands. +--- + +`@pyreon/cli` provides command-line tools for Pyreon projects including diagnostics (`doctor`), code generation (`generate`), and project context inspection (`context`). + + + +## Installation + +```package-install +@pyreon/cli +``` + +## Overview + +### `doctor` + +The `doctor` command checks your project setup to catch common issues early. + +- Verifies that required dependencies are installed and compatible +- Validates Pyreon configuration files (`pyreon.config.ts`, Vite plugin setup, etc.) +- Checks TypeScript and build tool settings for known pitfalls +- Reports a summary of passes, warnings, and errors + +```bash +pyreon doctor +``` + +### `generate` + +The `generate` command scaffolds new code into your project. + +- Generates components with the correct file structure and boilerplate +- Scaffolds stores with signal declarations and actions +- Creates route files wired into your router configuration + +```bash +pyreon generate component MyButton +pyreon generate store auth +pyreon generate route /settings +``` + +### `context` + +The `context` command inspects your project structure and outputs a machine-readable summary designed for AI coding assistants. + +- Lists detected routes, components, stores, and islands +- Outputs JSON that can be piped into an LLM prompt or MCP server +- Used internally by `@pyreon/mcp` to provide project-aware assistance + +```bash +pyreon context +``` diff --git a/content/docs/cli/meta.json b/content/docs/cli/meta.json new file mode 100644 index 0000000..da209d5 --- /dev/null +++ b/content/docs/cli/meta.json @@ -0,0 +1,5 @@ +{ + "title": "CLI", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/code/meta.json b/content/docs/code/meta.json new file mode 100644 index 0000000..8cba1de --- /dev/null +++ b/content/docs/code/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/code", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/connector-document/index.mdx b/content/docs/connector-document/index.mdx new file mode 100644 index 0000000..993adab --- /dev/null +++ b/content/docs/connector-document/index.mdx @@ -0,0 +1,90 @@ +--- +title: Connector Document +description: Bridge between Pyreon UI system styled components and @pyreon/document for multi-format rendering. +--- + +`@pyreon/connector-document` bridges Pyreon's UI system styled components with the `@pyreon/document` rendering pipeline, enabling styled components to render across 14+ output formats (PDF, DOCX, email, etc.). + + + +## Installation + +```package-install +@pyreon/connector-document +``` + +## Overview + +When you build components with `@pyreon/rocketstyle` or `@pyreon/styler`, their styles live in the CSS-in-JS layer. To export those components to non-browser formats (PDF, DOCX, Slack, etc.) via `@pyreon/document`, the styles need to be extracted and converted into a format the document renderers understand. + +`@pyreon/connector-document` handles this extraction. It walks a styled component tree, resolves all CSS-in-JS styles into inline style objects, and produces a document node tree that `@pyreon/document` renderers can consume. + +## How It Works + +1. **Extract** -- `extractDocumentTree()` traverses a Pyreon component tree and collects the rendered output along with resolved styles. +2. **Resolve** -- `resolveStyles()` converts CSS class-based styles into flat style objects compatible with document primitives. +3. **Parse** -- CSS value parsers (`parseCssDimension`, `parseBoxModel`, `parseFontWeight`, `parseLineHeight`) normalize CSS values into the units expected by each output format. + +## Usage + +```tsx +import { extractDocumentTree, resolveStyles } from '@pyreon/connector-document' +import { render } from '@pyreon/document' + +// Extract the styled component tree into document nodes +const tree = extractDocumentTree(MyStyledComponent, { data: myData }) + +// Render to any format +const pdf = await render(tree, 'pdf') +const docx = await render(tree, 'docx') +const email = await render(tree, 'email') +``` + +## CSS Value Parsers + +The package includes parsers that normalize CSS values for document renderers: + +```tsx +import { + parseCssDimension, + parseBoxModel, + parseFontWeight, + parseLineHeight, +} from '@pyreon/connector-document' + +parseCssDimension('16px') // { value: 16, unit: 'px' } +parseCssDimension('1.5rem') // { value: 1.5, unit: 'rem' } +parseBoxModel('8px 16px') // { top: 8, right: 16, bottom: 8, left: 16 } +parseFontWeight('bold') // 700 +parseLineHeight('1.5') // 1.5 +``` + +## API Reference + +| Export | Type | Description | +|---|---|---| +| `extractDocumentTree` | Function | Walks a styled component tree and produces document nodes | +| `resolveStyles` | Function | Converts CSS classes to inline style objects | +| `parseCssDimension` | Function | Parses a CSS dimension string (e.g., `'16px'`) into value and unit | +| `parseBoxModel` | Function | Parses CSS box model shorthand (margin/padding) | +| `parseFontWeight` | Function | Parses CSS font-weight keywords and numbers | +| `parseLineHeight` | Function | Parses CSS line-height values | + +## Types + +| Type | Description | +|---|---| +| `DocNode` | A node in the extracted document tree | +| `DocChild` | Child node type (text string or DocNode) | +| `NodeType` | Union of document node type identifiers | +| `ResolvedStyles` | Flat style object after CSS resolution | +| `ExtractOptions` | Options for `extractDocumentTree` | +| `DocumentMarker` | Marker interface for document extraction boundaries | + +## Key Features + +- Connects styler-powered components to document primitives +- Enables design-system-consistent exports across 14+ formats +- CSS value parsers for normalizing dimensions, box model, font weight, and line height +- Works with `@pyreon/rocketstyle` and `@pyreon/styler` components +- Produces document node trees compatible with all `@pyreon/document` renderers diff --git a/content/docs/connector-document/meta.json b/content/docs/connector-document/meta.json new file mode 100644 index 0000000..8b115a3 --- /dev/null +++ b/content/docs/connector-document/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/connector-document", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/create-zero/index.mdx b/content/docs/create-zero/index.mdx new file mode 100644 index 0000000..0302efa --- /dev/null +++ b/content/docs/create-zero/index.mdx @@ -0,0 +1,54 @@ +--- +title: "@pyreon/create-zero" +description: Project scaffolding tool for creating new Pyreon Zero applications. +--- + +`@pyreon/create-zero` scaffolds new Pyreon Zero projects with a single command. It sets up the project structure, dependencies, configuration, and a starter template. + + + +## Installation + +```bash +bun create @pyreon/zero my-app +``` + +Or with npx: + +```bash +npx @pyreon/create-zero my-app +``` + +## Overview + +Running the scaffolding command creates a new directory with a fully configured Pyreon Zero project: + +``` +my-app/ +├── src/ +│ ├── routes/ +│ ├── components/ +│ ├── stores/ +│ └── app.tsx +├── public/ +├── pyreon.config.ts +├── vite.config.ts +├── tsconfig.json +└── package.json +``` + +The generated project includes: + +- **Pyreon Zero** with all fundamentals packages via `@pyreon/meta` +- **Vite** preconfigured with `@pyreon/vite-plugin` +- **TypeScript** with strict mode and Pyreon-specific type settings +- **Router** with a starter home route and layout +- **File-based routing** convention ready to use + +After scaffolding, start the dev server: + +```bash +cd my-app +bun install +bun dev +``` diff --git a/content/docs/create-zero/meta.json b/content/docs/create-zero/meta.json new file mode 100644 index 0000000..4f698bb --- /dev/null +++ b/content/docs/create-zero/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Create Zero", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/devtools/index.mdx b/content/docs/devtools/index.mdx new file mode 100644 index 0000000..e0cdc91 --- /dev/null +++ b/content/docs/devtools/index.mdx @@ -0,0 +1,44 @@ +--- +title: "@pyreon/devtools" +description: Chrome DevTools extension for inspecting Pyreon component trees, signals, and performance. +--- + +`@pyreon/devtools` is a Chrome DevTools extension for inspecting Pyreon applications. It provides a component tree view, signal inspection, and performance monitoring. + + + +## Installation + +Install from the [Chrome Web Store](https://chromewebstore.google.com/) or build from source: + +```bash +git clone https://github.com/pyreon/devtools.git +cd devtools +bun install +bun run build +``` + +Then load the `dist/` folder as an unpacked extension in `chrome://extensions`. + +## Overview + +### Execution Contexts + +The extension is composed of four execution contexts that work together: + +1. **Page hook** — injected into the inspected page to instrument Pyreon's runtime, capturing component mounts, signal updates, and render timings. +2. **Content script** — bridges between the page hook and the extension background, forwarding messages across the isolated world boundary. +3. **Background service worker** — coordinates communication between the content script and any open DevTools panels, maintaining connection state. +4. **DevTools panel** — the UI you interact with inside Chrome DevTools, rendering the component tree, signal inspector, and performance graphs. + +### Component Tree Visualization + +The component tree panel shows every mounted Pyreon component in a collapsible hierarchy. Selecting a component reveals its current props, internal signals, and computed values. Components re-rendering in real time are highlighted so you can spot unnecessary updates. + +### Signal State Inspection + +The signals panel lists every signal and computed value in the selected component's scope. Each entry shows the current value, the number of subscribers, and a history of recent changes. You can manually set a signal's value from the panel for quick debugging. + +### Performance Monitoring + +The performance tab records render durations and signal propagation times. Use it to identify slow components or overly broad signal dependencies that trigger excessive re-renders. diff --git a/content/docs/devtools/meta.json b/content/docs/devtools/meta.json new file mode 100644 index 0000000..7f92a1e --- /dev/null +++ b/content/docs/devtools/meta.json @@ -0,0 +1,5 @@ +{ + "title": "DevTools", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/document-primitives/index.mdx b/content/docs/document-primitives/index.mdx new file mode 100644 index 0000000..801faa3 --- /dev/null +++ b/content/docs/document-primitives/index.mdx @@ -0,0 +1,106 @@ +--- +title: Document Primitives +description: Rocketstyle document components that render in the browser and export to 18 formats. +--- + +`@pyreon/document-primitives` provides pre-styled document components built with `@pyreon/rocketstyle` that render in the browser and export to 18 formats via `@pyreon/document`. + + + +## Installation + +```package-install +@pyreon/document-primitives +``` + +## Overview + +Document Primitives are Rocketstyle-powered components that serve a dual purpose: they render in the browser for live preview and export to any format supported by `@pyreon/document` (PDF, DOCX, email, Slack, etc.). Because they are built on `@pyreon/rocketstyle`, they support multi-dimensional styling (themes, sizes, variants) while maintaining consistent output across all formats. + +These primitives mirror the JSX primitives from `@pyreon/document` but add design-system integration through the Pyreon UI system. + +## Components + +| Component | Description | +|---|---| +| `DocDocument` | Root document container with metadata (title, author) | +| `DocPage` | Page with size, orientation, margin, header, footer | +| `DocSection` | Layout container with direction, gap, padding, background | +| `DocRow` | Horizontal layout container | +| `DocColumn` | Column within a row layout | +| `DocHeading` | Heading levels h1--h6 | +| `DocText` | Paragraph with bold, italic, color, size, align | +| `DocLink` | Hyperlink | +| `DocImage` | Image with width, height, alt, caption | +| `DocTable` | Data table with columns, rows, striped, bordered | +| `DocList` | Ordered or unordered list | +| `DocListItem` | Individual list item | +| `DocCode` | Code block with language | +| `DocDivider` | Horizontal rule | +| `DocSpacer` | Vertical gap | +| `DocButton` | CTA button (VML in email, styled link in PDF) | +| `DocQuote` | Block quote | +| `DocPageBreak` | Force page break (PDF/DOCX) | + +## Usage + +```tsx +import { + DocDocument, + DocPage, + DocHeading, + DocText, + DocTable, +} from '@pyreon/document-primitives' +import { render } from '@pyreon/document' + +function Invoice({ data }) { + return ( + + + Invoice #{data.id} + {data.date} + [i.name, i.qty, `$${i.price}`])} + striped + /> + Total: ${data.total} + + + ) +} + +// Render in browser for preview, or export +const pdf = await render(, 'pdf') +const email = await render(, 'email') +``` + +## Rocketstyle Integration + +Because these components are built with `@pyreon/rocketstyle`, they support dimension-based styling: + +```tsx +// DocHeading with theme and size dimensions +Large Primary Heading + +// DocButton with variant +Pay Now +``` + +## Connector Document Bridge + +Document Primitives use `@pyreon/connector-document` under the hood to resolve their Rocketstyle-based styles into the format expected by `@pyreon/document` renderers. This means your design tokens (colors, spacing, typography) are preserved consistently across all 18 output formats. + +## Key Features + +- Rocketstyle-powered primitives with theme, size, and variant dimensions +- Render in the browser for live document preview +- Export to 18 formats via `@pyreon/document` pipeline +- Design-system-consistent output across PDF, DOCX, email, Slack, and more +- Full set of document building blocks (headings, tables, images, buttons, etc.) +- Bridged to document renderers via `@pyreon/connector-document` diff --git a/content/docs/document-primitives/meta.json b/content/docs/document-primitives/meta.json new file mode 100644 index 0000000..3839e2a --- /dev/null +++ b/content/docs/document-primitives/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/document-primitives", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/document/meta.json b/content/docs/document/meta.json new file mode 100644 index 0000000..612cd9c --- /dev/null +++ b/content/docs/document/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/document", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/feature/meta.json b/content/docs/feature/meta.json new file mode 100644 index 0000000..1f4dd44 --- /dev/null +++ b/content/docs/feature/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/feature", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/flow/meta.json b/content/docs/flow/meta.json new file mode 100644 index 0000000..ffd8ad0 --- /dev/null +++ b/content/docs/flow/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/flow", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/hotkeys/meta.json b/content/docs/hotkeys/meta.json new file mode 100644 index 0000000..b188482 --- /dev/null +++ b/content/docs/hotkeys/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/hotkeys", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/index.mdx b/content/docs/index.mdx index e959064..05844b7 100644 --- a/content/docs/index.mdx +++ b/content/docs/index.mdx @@ -27,6 +27,9 @@ The foundation — reactivity engine, component model, renderers, router, and bu | [@pyreon/head](/docs/head) | Reactive document head management with SSR support | | [@pyreon/server](/docs/server) | SSR handler, SSG, island architecture, and middleware | | [@pyreon/vite-plugin](/docs/vite-plugin) | Vite integration with JSX transform and HMR | +| [@pyreon/typescript](/docs/typescript) | Shared TypeScript configuration presets | +| [@pyreon/cli](/docs/cli) | CLI tools — doctor, generate, and context commands | +| [@pyreon/mcp](/docs/mcp) | MCP server for AI-assisted development | ## Compatibility Layers @@ -72,6 +75,10 @@ Signal-native state management, forms, i18n, and data fetching. | [@pyreon/query](/docs/query) | TanStack Query adapter with Suspense and SSR dehydration | | [@pyreon/table](/docs/table) | TanStack Table adapter for reactive table state | | [@pyreon/virtual](/docs/virtual) | TanStack Virtual adapter for virtual scrolling | +| [@pyreon/machine](/docs/machine) | Reactive state machines with type-safe transitions | +| [@pyreon/storage](/docs/storage) | Reactive client-side storage — localStorage, sessionStorage, cookies, IndexedDB | +| [@pyreon/permissions](/docs/permissions) | Type-safe reactive permissions — RBAC, ABAC, feature flags | +| [@pyreon/hotkeys](/docs/hotkeys) | Keyboard shortcut management with scopes and modifiers | ## Meta-Framework @@ -80,6 +87,8 @@ Zero-config full-stack framework and developer tooling. | Package | Description | |---------|-------------| | [@pyreon/zero](/docs/zero) | Full-stack meta-framework — file routing, SSR/SSG/ISR, optimized components | +| [@pyreon/create-zero](/docs/create-zero) | Project scaffolding for new Zero applications | +| [@pyreon/meta](/docs/meta) | Barrel package re-exporting the full fundamentals ecosystem | | [@pyreon/storybook](/docs/storybook) | Storybook renderer for developing and documenting Pyreon components | ## UI System @@ -88,12 +97,36 @@ Styling, theming, components, hooks, and animations. | Package | Description | |---------|-------------| +| [@pyreon/ui-core](/docs/ui-core) | Core initialization, CSS engine connector, and shared utilities | | [@pyreon/styler](/docs/styler) | CSS-in-JS engine with theme support | | [@pyreon/unistyle](/docs/unistyle) | Responsive breakpoints and media query utilities | | [@pyreon/hooks](/docs/hooks) | 16 signal-based hooks for common UI patterns | | [@pyreon/elements](/docs/elements) | Foundational components — Element, List, Overlay, Portal, Text | +| [@pyreon/attrs](/docs/attrs) | Chainable component factory for composing default props | +| [@pyreon/rocketstyle](/docs/rocketstyle) | Multi-dimensional style composition — themes, sizes, variants | | [@pyreon/coolgrid](/docs/coolgrid) | Responsive grid system with Container, Row, Col | +| [@pyreon/kinetic](/docs/kinetic) | CSS-transition animation components — Transition, Stagger, Collapse | | [@pyreon/kinetic-presets](/docs/kinetic-presets) | 120+ animation presets and composition utilities | +| [@pyreon/connector-document](/docs/connector-document) | Bridge between styled components and @pyreon/document | +| [@pyreon/document-primitives](/docs/document-primitives) | Rocketstyle document components for multi-format export | + +## Ecosystem + +Specialized packages for rich application features. + +| Package | Description | +|---------|-------------| +| [@pyreon/document](/docs/document) | Universal document rendering — one template, 14+ output formats | +| [@pyreon/charts](/docs/charts) | Reactive ECharts bridge with lazy loading | +| [@pyreon/code](/docs/code) | Reactive CodeMirror 6 code editor with signals | +| [@pyreon/flow](/docs/flow) | Reactive flow diagrams with signal-native nodes and auto-layout | +| [@pyreon/feature](/docs/feature) | Schema-driven CRUD primitives with auto-generated hooks | + +## Developer Tools + +| Package | Description | +|---------|-------------| +| [@pyreon/devtools](/docs/devtools) | Chrome DevTools extension for component tree and signal inspection | ## Quick Start diff --git a/content/docs/kinetic/index.mdx b/content/docs/kinetic/index.mdx new file mode 100644 index 0000000..c2cf373 --- /dev/null +++ b/content/docs/kinetic/index.mdx @@ -0,0 +1,198 @@ +--- +title: Kinetic +description: CSS-transition-based animation components for enter/leave transitions, staggered animations, and collapsible content. +--- + +`@pyreon/kinetic` provides CSS-transition-based animation components for Pyreon. It includes `Transition` for enter/leave animations, `Stagger` for sequenced group animations, and `Collapse` for height-animated expand/collapse. + + + +## Installation + +```package-install +@pyreon/kinetic +``` + +## Overview + +Kinetic builds on native CSS transitions to animate elements as they enter and leave the DOM. Instead of keyframe-based animation libraries, it applies CSS classes or inline styles at the right moments during the transition lifecycle, giving you full control with minimal runtime overhead. + +The library exposes four main primitives: + +- **Transition** -- wraps a single child and applies CSS classes (or inline styles) during enter/leave phases. +- **TransitionGroup** -- manages a keyed list of children, animating additions and removals. +- **Stagger** -- sequences transitions across a list of children with a configurable delay between each. +- **Collapse** -- animates height between `0` and `auto` for expand/collapse patterns. + +## Transition + +The `Transition` component wraps a single child element and orchestrates enter/leave animations controlled by a reactive `show` accessor. + +### Class-Based Transitions + +```tsx +import { kinetic } from '@pyreon/kinetic' +import { signal } from '@pyreon/reactivity' + +const visible = signal(true) + + visible()} + enter="transition-opacity duration-300" + enterFrom="opacity-0" + enterTo="opacity-100" + leave="transition-opacity duration-200" + leaveFrom="opacity-100" + leaveTo="opacity-0" +> +
Animated content
+ +``` + +### Style-Based Transitions + +For zero-CSS setups, use inline style objects instead of class names: + +```tsx + visible()} + enterStyle={{ opacity: 0 }} + enterToStyle={{ opacity: 1 }} + enterTransition="opacity 300ms ease-out" + leaveStyle={{ opacity: 1 }} + leaveToStyle={{ opacity: 0 }} + leaveTransition="opacity 200ms ease-in" +> +
Fading content
+ +``` + +### Lifecycle Callbacks + +```tsx + visible()} + enterStyle={{ opacity: 0 }} + enterToStyle={{ opacity: 1 }} + enterTransition="opacity 300ms ease-out" + onEnter={() => console.log('entering')} + onAfterEnter={() => console.log('entered')} + onLeave={() => console.log('leaving')} + onAfterLeave={() => console.log('left')} +> +
Content
+ +``` + +## Stagger + +`Stagger` sequences transitions across a list of children, applying a configurable delay (`interval`) between each child's animation start. + +```tsx + visible()} + interval={80} + enterStyle={{ opacity: 0, transform: 'translateY(16px)' }} + enterToStyle={{ opacity: 1, transform: 'translateY(0)' }} + enterTransition="opacity 300ms ease-out, transform 300ms ease-out" + leaveStyle={{ opacity: 1 }} + leaveToStyle={{ opacity: 0 }} + leaveTransition="opacity 200ms ease-in" + reverseLeave +> +
Item 1
+
Item 2
+
Item 3
+ +``` + +| Prop | Type | Default | Description | +|---|---|---|---| +| `interval` | `number` | `50` | Delay in ms between each child's animation start | +| `reverseLeave` | `boolean` | `false` | Reverses stagger order on leave | + +## Collapse + +`Collapse` animates an element's height between `0` and `auto`, useful for accordion and disclosure patterns. + +```tsx + expanded()} + transition="height 300ms ease" +> +
Collapsible content that can be any height
+ +``` + +| Prop | Type | Default | Description | +|---|---|---|---| +| `transition` | `string` | `"height 300ms ease"` | CSS transition shorthand for the height animation | + +## Built-in Presets + +Kinetic ships with ready-to-use animation presets that you can spread onto any `Transition` or `Stagger`: + +```tsx +import { fade, scaleIn, slideUp, slideDown, slideLeft, slideRight } from '@pyreon/kinetic' + + visible()} {...fade}> +
Fading content
+ + + visible()} {...slideUp}> +
Slides up into view
+ +``` + +Available presets: `fade`, `scaleIn`, `slideUp`, `slideDown`, `slideLeft`, `slideRight`. + +## Hooks + +### `useTransitionState` + +Low-level hook that powers the `Transition` component. Returns reactive `stage`, `shouldMount`, a `ref` callback, and a `complete` function. + +```tsx +import { useTransitionState } from '@pyreon/kinetic' + +const { stage, shouldMount, ref, complete } = useTransitionState({ + show: () => visible(), + appear: true, + timeout: 5000, +}) +``` + +### `useAnimationEnd` + +Listens for `transitionend` / `animationend` on an element and calls a callback when the animation finishes. + +```tsx +import { useAnimationEnd } from '@pyreon/kinetic' + +useAnimationEnd(elementRef, () => { + console.log('animation finished') +}) +``` + +## Transition Stages + +Every transition moves through four stages: + +| Stage | Description | +|---|---| +| `hidden` | Element is not mounted (or has `display: none` if `unmount={false}`) | +| `entering` | Enter classes/styles applied, animation in progress | +| `entered` | Enter animation complete, element fully visible | +| `leaving` | Leave classes/styles applied, animation in progress | + +## Key Features + +- CSS-transition-based -- no JavaScript animation loops, uses native browser transitions +- Class-based or style-based -- choose between utility classes or inline style objects +- Staggered group animations with configurable interval and reverse-leave +- Height-animated collapse for accordion/disclosure patterns +- Built-in presets for common animations (fade, scale, slide) +- Lifecycle callbacks (`onEnter`, `onAfterEnter`, `onLeave`, `onAfterLeave`) +- Safety timeout prevents stuck animations (default 5000ms) +- Reduced-motion support via `useReducedMotion` hook +- Works with Pyreon's reactive system (`Signal`-based `show` accessor) diff --git a/content/docs/kinetic/meta.json b/content/docs/kinetic/meta.json new file mode 100644 index 0000000..509c2e1 --- /dev/null +++ b/content/docs/kinetic/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/kinetic", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/machine/meta.json b/content/docs/machine/meta.json new file mode 100644 index 0000000..1a3edb0 --- /dev/null +++ b/content/docs/machine/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/machine", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/meta.json b/content/docs/meta.json index ec37cc7..6c355ee 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -16,6 +16,7 @@ "server", "vite-plugin", "typescript", + "cli", "mcp", "---Compatibility Layers---", "react-compat", @@ -31,15 +32,35 @@ "query", "table", "virtual", + "machine", + "storage", + "permissions", + "hotkeys", "---Meta-Framework---", "zero", + "create-zero", + "meta", "storybook", "---UI System---", + "ui-core", "styler", "unistyle", "hooks", "elements", + "attrs", + "rocketstyle", "coolgrid", - "kinetic-presets" + "kinetic", + "kinetic-presets", + "connector-document", + "document-primitives", + "---Ecosystem---", + "document", + "charts", + "code", + "flow", + "feature", + "---Developer Tools---", + "devtools" ] } diff --git a/content/docs/meta/index.mdx b/content/docs/meta/index.mdx new file mode 100644 index 0000000..3eedf1f --- /dev/null +++ b/content/docs/meta/index.mdx @@ -0,0 +1,38 @@ +--- +title: "@pyreon/meta" +description: Barrel package re-exporting the full Pyreon fundamentals ecosystem for convenience. +--- + +`@pyreon/meta` is a barrel package that re-exports the entire Pyreon fundamentals ecosystem (store, form, validation, query, table, virtual, i18n, state-tree, feature, charts, code, document, flow, hotkeys, machine, permissions, storage, storybook) from a single import. + + + +## Installation + +```package-install +@pyreon/meta +``` + +## Overview + +Instead of installing each fundamentals package individually: + +```bash +bun add @pyreon/store @pyreon/form @pyreon/validation @pyreon/query @pyreon/table @pyreon/virtual @pyreon/i18n @pyreon/state-tree @pyreon/feature @pyreon/charts @pyreon/code @pyreon/document @pyreon/flow @pyreon/hotkeys @pyreon/machine @pyreon/permissions @pyreon/storage @pyreon/storybook +``` + +You can install `@pyreon/meta` once: + +```bash +bun add @pyreon/meta +``` + +All exports are available directly: + +```ts +import { createStore, createForm, createQuery, createTable } from "@pyreon/meta"; +``` + +### Used by `@pyreon/zero` + +`@pyreon/meta` is used internally by `@pyreon/zero` to bundle the full fundamentals layer. If you are already using `@pyreon/zero`, you do not need to install `@pyreon/meta` separately — it is included automatically. diff --git a/content/docs/meta/meta.json b/content/docs/meta/meta.json new file mode 100644 index 0000000..2d7d2ed --- /dev/null +++ b/content/docs/meta/meta.json @@ -0,0 +1,5 @@ +{ + "title": "Meta", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/permissions/meta.json b/content/docs/permissions/meta.json new file mode 100644 index 0000000..2d0c021 --- /dev/null +++ b/content/docs/permissions/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/permissions", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/rocketstyle/index.mdx b/content/docs/rocketstyle/index.mdx new file mode 100644 index 0000000..b4b6344 --- /dev/null +++ b/content/docs/rocketstyle/index.mdx @@ -0,0 +1,147 @@ +--- +title: Rocketstyle +description: Multi-dimensional style composition for Pyreon components -- themes, sizes, variants, and states. +--- + +`@pyreon/rocketstyle` enables multi-dimensional style composition for Pyreon components. Define orthogonal style dimensions (themes, sizes, variants, states) and compose them declaratively. + + + +## Installation + +```package-install +@pyreon/rocketstyle +``` + +## Overview + +Rocketstyle lets you define multiple independent style dimensions on a component -- for example, `theme`, `size`, `variant`, and `state`. Each dimension has a set of named values, and each value maps to a style callback. At render time, the active value from each dimension is resolved and all styles are merged together. + +This approach scales better than flat variant props because dimensions compose multiplicatively without requiring you to enumerate every combination. + +## Quick Start + +```tsx +import rocketstyle from '@pyreon/rocketstyle' +import { styled } from '@pyreon/styler' + +const BaseButton = styled('button')` + border: none; + border-radius: 4px; + cursor: pointer; + font-weight: 500; +` + +const Button = rocketstyle(BaseButton) + .theme({ + primary: { background: 'royalblue', color: 'white' }, + danger: { background: '#dc3545', color: 'white' }, + ghost: { background: 'transparent', color: '#333', border: '1px solid #ccc' }, + }) + .size({ + sm: { padding: '4px 8px', fontSize: '12px' }, + md: { padding: '8px 16px', fontSize: '14px' }, + lg: { padding: '12px 24px', fontSize: '16px' }, + }) + .state({ + disabled: { opacity: 0.5, cursor: 'not-allowed' }, + loading: { opacity: 0.7, cursor: 'wait' }, + }) + +// Dimensions become props + + + +``` + +## Dimensions + +Rocketstyle supports four built-in dimension types: + +| Dimension | Description | +|---|---| +| `theme` | Visual theme (e.g., primary, secondary, danger) | +| `size` | Size scale (e.g., sm, md, lg, xl) | +| `variant` | Structural variation (e.g., outlined, filled, text) | +| `state` | Interactive state (e.g., disabled, loading, active) | + +Each dimension is defined by calling the corresponding method on the rocketstyle builder and passing a map of named values to style objects or callbacks. + +## Style Callbacks + +Dimension values can be static objects or dynamic callbacks that receive the component's props and theme: + +```tsx +const Card = rocketstyle(BaseCard) + .theme({ + light: { background: '#fff', color: '#333' }, + dark: (props) => ({ + background: props.elevated ? '#2d2d2d' : '#1a1a1a', + color: '#e0e0e0', + }), + }) +``` + +## Chaining with Attrs + +Rocketstyle builds on `@pyreon/attrs`, so you can chain `.attrs()` calls alongside dimension definitions: + +```tsx +const IconButton = rocketstyle(BaseButton) + .attrs({ 'aria-label': 'icon button' }) + .theme({ + primary: { background: 'royalblue', color: 'white' }, + }) + .size({ + sm: { width: '32px', height: '32px' }, + md: { width: '40px', height: '40px' }, + }) +``` + +## Provider and Context + +Rocketstyle components can be configured at the tree level using the built-in `Provider`: + +```tsx +import { Provider } from '@pyreon/rocketstyle' + + + {/* All rocketstyle components inside inherit these defaults */} + + Also dark and small + +``` + +## Integration with Styler + +Rocketstyle is designed to work with `@pyreon/styler`. Dimension style objects are resolved into CSS classes via the styler's `styled` API, giving you scoped styles with deduplication and SSR support. + +## API Reference + +| Export | Type | Description | +|---|---|---| +| `rocketstyle` | Function | Wraps a component and returns a multi-dimension style builder | +| `Provider` | Component | Context provider for tree-level dimension defaults | +| `context` | Context | The raw Pyreon context object used by Provider | +| `isRocketComponent` | Function | Type guard to check if a value is a rocketstyle component | + +## Types + +| Type | Description | +|---|---| +| `Rocketstyle` | The builder interface with `.theme()`, `.size()`, `.variant()`, `.state()`, `.attrs()` | +| `RocketStyleComponent` | A component produced by the rocketstyle builder | +| `Dimensions` | Map of dimension names to their value definitions | +| `DimensionProps` | Props auto-generated from dimension definitions | +| `ThemeMode` | Theme mode configuration type | +| `StylesCb` | Style callback signature: `(props) => StyleObject` | + +## Key Features + +- Multi-dimensional style composition (theme, size, variant, state) +- Auto-generated props from dimension definitions +- Static style objects or dynamic style callbacks +- Built on `@pyreon/attrs` -- chainable `.attrs()` calls +- Tree-level defaults via Provider/Context +- Works with `@pyreon/styler` for scoped CSS-in-JS +- Full TypeScript support with inferred dimension props diff --git a/content/docs/rocketstyle/meta.json b/content/docs/rocketstyle/meta.json new file mode 100644 index 0000000..93a1bec --- /dev/null +++ b/content/docs/rocketstyle/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/rocketstyle", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/storage/meta.json b/content/docs/storage/meta.json new file mode 100644 index 0000000..9e38f86 --- /dev/null +++ b/content/docs/storage/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/storage", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/typescript/meta.json b/content/docs/typescript/meta.json new file mode 100644 index 0000000..92278d9 --- /dev/null +++ b/content/docs/typescript/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/typescript", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/content/docs/ui-core/index.mdx b/content/docs/ui-core/index.mdx new file mode 100644 index 0000000..acaf1da --- /dev/null +++ b/content/docs/ui-core/index.mdx @@ -0,0 +1,146 @@ +--- +title: UI Core +description: Core initialization, CSS engine connector, and shared utilities for the Pyreon UI system. +--- + +`@pyreon/ui-core` provides the foundation for Pyreon's UI system. It includes the `init()` function to configure the CSS engine, shared context providers, and utility functions used by other UI packages. + + + +## Installation + +```package-install +@pyreon/ui-core +``` + +## Overview + +UI Core is the shared foundation that all other Pyreon UI packages (`@pyreon/attrs`, `@pyreon/rocketstyle`, `@pyreon/elements`, etc.) depend on. It handles three responsibilities: + +1. **CSS engine initialization** -- the `init()` function connects a CSS engine (e.g., `@pyreon/styler`) so that styled components can inject styles. +2. **Context providers** -- shared context for theme state, breakpoints, and configuration that flows through the component tree. +3. **Shared utilities** -- pure helper functions (`merge`, `omit`, `pick`, `get`, `set`, `throttle`, `isEqual`, `isEmpty`) and component composition tools (`compose`, `hoistNonReactStatics`, `render`). + +## Initialization + +Call `init()` at your app's entry point to connect the CSS engine before rendering any UI components: + +```tsx +import { init } from '@pyreon/ui-core' +import { styled, css } from '@pyreon/styler' + +init({ + styled, + css, + // other CSS engine hooks as needed +}) +``` + +This must happen before any `@pyreon/rocketstyle` or `@pyreon/elements` components render, as they rely on the configured engine to generate and inject styles. + +## Context and Provider + +UI Core provides a shared context and `Provider` component for distributing configuration through the component tree: + +```tsx +import { Provider, context } from '@pyreon/ui-core' + + + + +``` + +## Utilities + +### Object Helpers + +```tsx +import { merge, omit, pick, get, set } from '@pyreon/ui-core' + +merge({ a: 1 }, { b: 2 }) // { a: 1, b: 2 } +omit({ a: 1, b: 2, c: 3 }, ['b']) // { a: 1, c: 3 } +pick({ a: 1, b: 2, c: 3 }, ['a']) // { a: 1 } +get({ a: { b: 1 } }, 'a.b') // 1 +set({}, 'a.b', 1) // { a: { b: 1 } } +``` + +### Comparison Helpers + +```tsx +import { isEqual, isEmpty } from '@pyreon/ui-core' + +isEqual({ a: 1 }, { a: 1 }) // true +isEmpty({}) // true +isEmpty({ a: 1 }) // false +``` + +### Component Composition + +```tsx +import { compose, hoistNonReactStatics } from '@pyreon/ui-core' + +// compose applies a chain of higher-order components +const EnhancedComponent = compose(withAuth, withTheme, withLogger)(BaseComponent) + +// hoistNonReactStatics copies statics from source to target +hoistNonReactStatics(WrappedComponent, OriginalComponent) +``` + +### Other + +```tsx +import { throttle, useStableValue } from '@pyreon/ui-core' + +const throttled = throttle(handleResize, 100) +``` + +## HTML Tag Constants + +UI Core exports lists of valid HTML tags used by other UI packages for prop filtering and element creation: + +```tsx +import { HTML_TAGS, HTML_TEXT_TAGS } from '@pyreon/ui-core' +``` + +## API Reference + +| Export | Type | Description | +|---|---|---| +| `init` | Function | Configures the CSS engine connector | +| `config` | Object | Current CSS engine configuration | +| `Provider` | Component | Shared context provider | +| `context` | Context | Raw Pyreon context object | +| `compose` | Function | HOC composition utility | +| `render` | Function | Component render helper | +| `hoistNonReactStatics` | Function | Copies static properties between components | +| `merge` | Function | Deep merge objects | +| `omit` | Function | Omit keys from an object | +| `pick` | Function | Pick keys from an object | +| `get` | Function | Get nested value by path | +| `set` | Function | Set nested value by path | +| `throttle` | Function | Throttle a function | +| `isEqual` | Function | Deep equality check | +| `isEmpty` | Function | Check if a value is empty | +| `useStableValue` | Hook | Returns a stable reference for a value | +| `HTML_TAGS` | Array | List of all valid HTML tag names | +| `HTML_TEXT_TAGS` | Array | List of HTML tags that contain text content | + +## Types + +| Type | Description | +|---|---| +| `CSSEngineConnector` | Interface for connecting a CSS engine to UI Core | +| `Breakpoints` | Breakpoint size map (e.g., `{ sm: 576, md: 768 }`) | +| `BreakpointKeys` | String union of breakpoint names | +| `HTMLTags` | Union type of all valid HTML tag names | +| `HTMLTextTags` | Union type of text-content HTML tags | +| `Render` | Render function type | + +## Key Features + +- `init()` configures the CSS engine at app startup +- Shared context provider for theme and breakpoint state +- Pure utility functions for object manipulation and comparison +- HOC composition and static hoisting tools +- HTML tag constants for prop filtering +- Foundation package for `@pyreon/attrs`, `@pyreon/rocketstyle`, and `@pyreon/elements` diff --git a/content/docs/ui-core/meta.json b/content/docs/ui-core/meta.json new file mode 100644 index 0000000..1e26f74 --- /dev/null +++ b/content/docs/ui-core/meta.json @@ -0,0 +1,5 @@ +{ + "title": "@pyreon/ui-core", + "defaultOpen": true, + "pages": ["index"] +} diff --git a/src/app/(home)/page.tsx b/src/app/(home)/page.tsx index 9c8611a..0b0fa22 100644 --- a/src/app/(home)/page.tsx +++ b/src/app/(home)/page.tsx @@ -125,6 +125,59 @@ const fundamentalsPackages = [ description: 'TanStack Virtual adapter for efficient virtual scrolling.', href: '/docs/virtual', }, + { + title: 'Machine', + description: 'Reactive state machines with type-safe transitions.', + href: '/docs/machine', + }, + { + title: 'Storage', + description: + 'Reactive client-side storage — localStorage, sessionStorage, cookies, IndexedDB.', + href: '/docs/storage', + }, + { + title: 'Permissions', + description: 'Type-safe reactive permissions — RBAC, ABAC, feature flags.', + href: '/docs/permissions', + }, + { + title: 'Hotkeys', + description: 'Keyboard shortcut management with scopes and modifier keys.', + href: '/docs/hotkeys', + }, +] + +const ecosystemPackages = [ + { + title: 'Document', + description: + 'Universal document rendering — one template, 14+ output formats.', + href: '/docs/document', + }, + { + title: 'Charts', + description: + 'Reactive ECharts bridge with lazy loading and signal-driven updates.', + href: '/docs/charts', + }, + { + title: 'Code', + description: + 'Reactive CodeMirror 6 code editor with signals, minimap, and diff editor.', + href: '/docs/code', + }, + { + title: 'Flow', + description: + 'Reactive flow diagrams with signal-native nodes, pan/zoom, and auto-layout.', + href: '/docs/flow', + }, + { + title: 'Feature', + description: 'Schema-driven CRUD primitives with auto-generated hooks.', + href: '/docs/feature', + }, ] const uiPackages = [ @@ -162,6 +215,24 @@ const uiPackages = [ '120+ animation presets and composition utilities for transitions.', href: '/docs/kinetic-presets', }, + { + title: 'Kinetic', + description: + 'CSS-transition animation components — Transition, Stagger, Collapse.', + href: '/docs/kinetic', + }, + { + title: 'Attrs', + description: + 'Chainable component factory for composing default props and behaviors.', + href: '/docs/attrs', + }, + { + title: 'Rocketstyle', + description: + 'Multi-dimensional style composition — themes, sizes, variants, states.', + href: '/docs/rocketstyle', + }, ] const features = [ @@ -247,7 +318,7 @@ export default function HomePage() {

A signal-based UI framework with fine-grained reactivity, no virtual DOM, streaming SSR, and compatibility layers for React, Vue, Solid, - and Preact — plus a full ecosystem of 27 packages. + and Preact — plus a full ecosystem of 50+ packages.

@@ -274,7 +345,7 @@ export default function HomePage() { {/* Stats */}
- 27 + 50+ Packages
@@ -392,18 +463,18 @@ export default function HomePage() { - {/* Fundamentals */} + {/* State & Data */}
@pyreon/*

- Ecosystem + State & Data

- State management, forms, i18n, data fetching, tables, and virtual - scrolling — all signal-native. + State management, forms, i18n, data fetching, permissions, storage, + and more — all signal-native.

@@ -443,6 +514,32 @@ export default function HomePage() {
+ {/* Ecosystem */} +
+
+ + @pyreon/* + +

+ Ecosystem +

+

+ Documents, charts, code editors, flow diagrams, and schema-driven + CRUD — specialized packages for rich applications. +

+
+ + {ecosystemPackages.map((pkg) => ( + + ))} + +
+ {/* CTA */}