diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 0000000..ce541c8 --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,18 @@ +# .github/workflows/publish.yml + +name: Publish + +on: + push: + branches: + - main + +jobs: + publish: + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write # The OIDC ID token is used for authentication with JSR. + steps: + - uses: actions/checkout@v4 + - run: npx jsr publish diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..a7b9d10 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,141 @@ +# Release Guide + +This guide covers the process for publishing Volt.js packages to npm and JSR. + +## Prerequisites + +### npm + +Ensure you have npm publishing rights: + +```bash +npm whoami +``` + +Make sure you're logged in: + +```bash +npm login +``` + +### JSR + +No setup required. JSR authentication happens via browser during first publish. + +## Pre-Release Checklist + +1. Ensure all tests pass + + ```bash + pnpm test:run + ``` + +2. Type check all packages + + ```bash + pnpm typecheck + ``` + +3. Build all packages + + ```bash + pnpm build + ``` + +4. Review changelog and update version numbers + +## Publishing voltx.js + +The core package is published as: + +- **npm**: `voltx.js` (unscoped) +- **JSR**: `@voltx.js/core` (scoped, JSR requires scopes) + +### 1. Update Version + +Update version in both files: + +- `lib/package.json` +- `lib/jsr.json` + +Use semantic versioning (semver): + +- Patch: bug fixes (0.1.0 → 0.1.1) +- Minor: new features, backward compatible (0.1.0 → 0.2.0) +- Major: breaking changes (0.1.0 → 1.0.0) + +### 2. Build Package + +```bash +cd lib +pnpm build +``` + +Verify build outputs: + +- `dist/volt.js` - Main framework bundle +- `dist/volt.css` - CSS framework +- `dist/index.d.ts` - TypeScript declarations + +### 3. Publish to npm + +```bash +cd lib +npm publish --provenance +``` + +The `--provenance` flag adds supply chain security metadata when publishing from GitHub Actions. + +### 4. Publish to JSR + +```bash +cd lib +npx jsr publish +``` + +First time: Browser window opens for authentication +Subsequent publishes: Uses cached credentials + +### 5. Verify Publication + +npm: + +```bash +npm view voltx.js +``` + +JSR: + +```bash +npx jsr info @voltx.js/core +``` + +Or visit: + +- npm: +- JSR: + +## Post-Release + +1. Create Git tag + + ```bash + git tag v0.1.0 + git push origin v0.1.0 + ``` + +2. Create GitHub release with changelog + +3. Update documentation if needed + +## To-Do + +Consider setting up GitHub Actions workflow to automate: + +- Publishing to npm +- Version bumping +- Building +- Git tagging +- GitHub release creation + +Consider using `bumpp` or `changeset` for automated version management across the monorepo. diff --git a/dev/package.json b/dev/package.json index 802fc46..d16c124 100644 --- a/dev/package.json +++ b/dev/package.json @@ -3,7 +3,9 @@ "version": "0.1.0", "description": "Local development CLI for Volt.js", "type": "module", + "author": "Owais Jamil", "license": "MIT", + "repository": { "type": "git", "url": "https://github.com/stormlightlabs/volt.git", "directory": "dev" }, "bin": { "volt": "./dist/index.js" }, "files": ["dist"], "main": "./dist/index.js", diff --git a/docs/internals/debugging.md b/docs/internals/debugging.md index 30281d5..1dcb18a 100644 --- a/docs/internals/debugging.md +++ b/docs/internals/debugging.md @@ -1,7 +1,7 @@ # Debugging -The Volt.js debugging system provides introspection and visualization tools for reactive primitives. -It's a lazy-loadable module (`volt/debug`) that doesn't affect production bundle size. +The VoltX.js debugging system provides introspection and visualization tools for reactive primitives. +It's a lazy-loadable module (`voltx.js/debug`) that doesn't affect production bundle size. ## Architecture @@ -101,14 +101,14 @@ The logger provides multiple output formats: For development, import debug utilities directly: ```ts -import { debugSignal, debugComputed, logAllSignals, buildDependencyGraph } from 'volt/debug'; +import { debugSignal, debugComputed, logAllSignals, buildDependencyGraph } from 'voltx.js/debug'; ``` For debugging existing code, attach debugger to existing signals: ```ts -import { signal } from 'volt'; -import { attachDebugger, vdebugger } from 'volt/debug'; +import { signal } from 'voltx.js'; +import { attachDebugger, vdebugger } from 'voltx.js/debug'; const count = signal(0); attachDebugger(count, 'signal', 'count'); @@ -118,7 +118,7 @@ vdebugger.log(count); For browser console debugging, expose vdebugger globally: ```ts -import { vdebugger } from 'volt/debug'; +import { vdebugger } from 'voltx.js/debug'; window.vdebugger = vdebugger; ``` diff --git a/docs/spec/plugin-spec.md b/docs/spec/plugin-spec.md index 2391e7f..83da83e 100644 --- a/docs/spec/plugin-spec.md +++ b/docs/spec/plugin-spec.md @@ -1,4 +1,4 @@ -# Volt Plugin System Spec +# VoltX Plugin System Spec ## Overview @@ -67,7 +67,7 @@ interface PluginContext { ### Example: Custom Tooltip Plugin ```ts -import { registerPlugin } from 'volt'; +import { registerPlugin } from 'voltx.js'; registerPlugin('tooltip', (context, value) => { const tooltip = document.createElement('div'); diff --git a/lib/.npmignore b/lib/.npmignore new file mode 100644 index 0000000..e9134db --- /dev/null +++ b/lib/.npmignore @@ -0,0 +1,32 @@ +# Development files +*.log +*.swp +*.swo +*~ + +# Test files +test/ +**/*.test.ts +**/*.spec.ts +coverage/ + +# Build config +tsconfig*.json +vite.config.ts +vitest.config.ts +postcss.config.js +eslint.config.js + +# Development +node_modules/ +.DS_Store +.vscode/ +.idea/ + +# Demo +demo/ +index.html + +# Keep dist and src +!dist/ +!src/ diff --git a/lib/LICENSE b/lib/LICENSE new file mode 100644 index 0000000..82cf94e --- /dev/null +++ b/lib/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 [Owais J] + +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. diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 0000000..82e4897 --- /dev/null +++ b/lib/README.md @@ -0,0 +1,68 @@ +# VoltX.js + +A lightweight reactive framework for declarative UIs. Build interactive applications using only HTML attributes powered by signals. + +## Features + +- Declarative HTML-driven reactivity via `data-volt-*` attributes +- Signal-based state management with automatic DOM updates +- Zero dependencies, under 15 KB gzipped +- No virtual DOM, no build step required +- Server-side rendering and hydration support +- Built-in plugins for persistence, routing, and scroll management + +## Installation + +### npm + +```bash +npm install voltx.js +``` + +### JSR + +```bash +npx jsr add @voltx/core +``` + +### Deno + +```typescript +import { charge, signal } from "jsr:@voltx/core"; +``` + +## Quick Start + +```html +
+

+ +
+ + +``` + +## Using CSS + +Import the optional CSS framework: + +```typescript +import 'voltx.js/css'; +``` + +Or include via CDN: + +```html + +``` + +## Documentation + +Full documentation available at [your-docs-url] + +## License + +MIT diff --git a/lib/jsr.json b/lib/jsr.json new file mode 100644 index 0000000..b2ef4d2 --- /dev/null +++ b/lib/jsr.json @@ -0,0 +1,7 @@ +{ + "name": "@voltx/core", + "version": "0.1.0", + "license": "MIT", + "exports": { ".": "./src/index.ts", "./debug": "./src/debug.ts", "./css": "./dist/volt.css" }, + "publish": { "include": ["src", "dist", "README.md", "LICENSE"] } +} diff --git a/lib/package.json b/lib/package.json index f1c991b..79e0532 100644 --- a/lib/package.json +++ b/lib/package.json @@ -1,19 +1,38 @@ { - "name": "volt", - "private": true, + "name": "voltx.js", "version": "0.1.0", + "description": "A lightweight reactive framework for declarative UIs", "type": "module", + "author": "Owais Jamil", + "license": "MIT", + "repository": { "type": "git", "url": "https://github.com/stormlightlabs/volt.git", "directory": "lib" }, + "keywords": ["reactive", "signals", "framework", "ui", "declarative", "html", "dom", "frontend"], + "main": "./dist/volt.js", + "module": "./dist/volt.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { "types": "./dist/index.d.ts", "import": "./dist/volt.js" }, + "./debug": { "types": "./dist/debug.d.ts", "import": "./dist/debug.js" }, + "./css": "./dist/volt.css", + "./package.json": "./package.json" + }, + "files": ["dist", "src", "README.md"], "scripts": { "dev": "vite", "build": "pnpm build:lib && pnpm build:css", - "build:lib": "tsc && vite build --mode lib", + "build:lib": "tsc -p tsconfig.build.json && vite build --mode lib", "build:css": "postcss src/styles/index.css -o dist/volt.css", "build:css:min": "postcss src/styles/index.css -o dist/volt.min.css --env production", "preview": "vite preview", "test": "vitest", "test:run": "vitest run", - "typecheck": "tsc --noEmit" + "typecheck": "tsc --noEmit", + "prepublishOnly": "pnpm build && pnpm test:run", + "publish:npm": "npm publish --access=public", + "publish:jsr": "npx jsr publish", + "publish:all": "pnpm publish:npm && pnpm publish:jsr" }, + "publishConfig": { "access": "public" }, "devDependencies": { "@testing-library/dom": "^10.4.1", "@testing-library/jest-dom": "^6.9.1", diff --git a/lib/src/debug.ts b/lib/src/debug.ts index e15b295..781e833 100644 --- a/lib/src/debug.ts +++ b/lib/src/debug.ts @@ -2,11 +2,11 @@ * Volt.js Debug Utilities * * Lazy-loadable debugging module for signal introspection and visualization. - * Import from 'volt/debug' to access these utilities without affecting production bundle size. + * Import from 'voltx.js/debug' to access these utilities without affecting production bundle size. * * @example * ```ts - * import { debugSignal, debugComputed, logAllSignals } from 'volt/debug'; + * import { debugSignal, debugComputed, logAllSignals } from 'voltx.js/debug'; * * const count = debugSignal(0, 'count'); * const doubled = debugComputed(() => count.get() * 2, 'doubled'); @@ -14,7 +14,7 @@ * logAllSignals(); * ``` * - * @module volt/debug + * @module voltx.js/debug * @packageDocumentation */ diff --git a/lib/src/demo/index.ts b/lib/src/demo/index.ts index 90f2912..ecfdf06 100644 --- a/lib/src/demo/index.ts +++ b/lib/src/demo/index.ts @@ -20,7 +20,7 @@ registerPlugin("persist", persistPlugin); registerPlugin("scroll", scrollPlugin); registerPlugin("url", urlPlugin); -const message = signal("Welcome to Volt.js Demo"); +const message = signal("Welcome to the Volt.js Demo"); const count = signal(0); const doubled = computed(() => count.get() * 2); @@ -172,11 +172,22 @@ export const demoScope = { scrollToSection, }; -/** - * Build the complete demo structure programmatically - */ +const buildNav = () => + dom.nav( + null, + dom.a({ href: "#typography" }, "Typography"), + " | ", + dom.a({ href: "#interactivity" }, "Interactivity"), + " | ", + dom.a({ href: "#forms" }, "Forms"), + " | ", + dom.a({ href: "#reactivity" }, "Reactivity"), + " | ", + dom.a({ href: "#plugins" }, "Plugins"), + ); + function buildDemoStructure(): HTMLElement { - const container = dom.div( + return dom.div( null, dom.header( null, @@ -188,18 +199,7 @@ function buildDemoStructure(): HTMLElement { null, "This demo demonstrates both the framework's reactive capabilities and the elegant, semantic styling of Volt CSS. No CSS classes needed!", ), - ), - dom.nav( - null, - dom.a({ href: "#typography" }, "Typography"), - " | ", - dom.a({ href: "#interactivity" }, "Interactivity"), - " | ", - dom.a({ href: "#forms" }, "Forms"), - " | ", - dom.a({ href: "#reactivity" }, "Reactivity"), - " | ", - dom.a({ href: "#plugins" }, "Plugins"), + buildNav(), ), ), dom.el( @@ -229,8 +229,6 @@ function buildDemoStructure(): HTMLElement { ), ), ); - - return container; } export function setupDemo() { diff --git a/lib/src/demo/sections/interactivity.ts b/lib/src/demo/sections/interactivity.ts index 4ec97b3..1ed0274 100644 --- a/lib/src/demo/sections/interactivity.ts +++ b/lib/src/demo/sections/interactivity.ts @@ -21,7 +21,7 @@ export function createInteractivitySection(): HTMLElement { null, "Modern browsers support the dialog element natively, providing built-in accessibility features and keyboard handling (ESC to close, focus trapping, etc.).", ), - " Volt CSS styles it elegantly, and Volt.js handles the interaction.", + " VoltX CSS styles it elegantly, and VoltX.js handles the interaction.", ), dom.button({ "data-volt-on-click": "openDialog" }, "Open Dialog"), dom.p({ "data-volt-if": "dialogMessage.get()", "data-volt-text": "dialogMessage" }), @@ -32,11 +32,7 @@ export function createInteractivitySection(): HTMLElement { dom.header( null, dom.h3(null, "Dialog Demo"), - dom.button({ - "data-volt-on-click": "closeDialog", - "aria-label": "Close", - style: "float: right; background: none; border: none; font-size: 1.5rem; cursor: pointer;", - }, "×"), + dom.button({ "data-volt-on-click": "closeDialog", "aria-label": "Close" }, "×"), ), dom.form( { "data-volt-on-submit": "submitDialog" }, @@ -48,7 +44,7 @@ export function createInteractivitySection(): HTMLElement { required: true, }), dom.footer( - { style: "display: flex; gap: 1rem; justify-content: flex-end;" }, + null, dom.button({ type: "button", "data-volt-on-click": "closeDialog" }, "Cancel"), dom.button({ type: "submit" }, "Submit"), ), diff --git a/lib/src/index.ts b/lib/src/index.ts index ecc200e..f57c86f 100644 --- a/lib/src/index.ts +++ b/lib/src/index.ts @@ -1,5 +1,5 @@ /** - * Volt.js - A lightweight reactive framework for declarative UIs + * VoltX.js - A lightweight reactive framework for declarative UIs * * @packageDocumentation */ diff --git a/lib/tsconfig.build.json b/lib/tsconfig.build.json new file mode 100644 index 0000000..bfea314 --- /dev/null +++ b/lib/tsconfig.build.json @@ -0,0 +1,12 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "noEmit": false, + "declaration": true, + "declarationMap": true, + "emitDeclarationOnly": true, + "outDir": "./dist", + "rootDir": "./src" + }, + "include": ["src"] +} diff --git a/lib/vite.config.ts b/lib/vite.config.ts index 9731549..5d225f3 100644 --- a/lib/vite.config.ts +++ b/lib/vite.config.ts @@ -34,7 +34,14 @@ export default defineConfig(({ mode }) => ({ }, build: mode === "lib" ? { - lib: { entry: path.resolve(__dirname, "src/index.ts"), name: "Volt", fileName: "volt", formats: ["es"] }, + lib: { + entry: { + volt: path.resolve(__dirname, "src/index.ts"), + debug: path.resolve(__dirname, "src/debug.ts"), + }, + name: "Volt", + formats: ["es"], + }, rolldownOptions: { output: { assetFileNames: "volt.[ext]" } }, } : undefined, diff --git a/package.json b/package.json index 01f69b2..32fe47f 100644 --- a/package.json +++ b/package.json @@ -1,14 +1,14 @@ { - "name": "volt-monorepo", + "name": "voltx.js-monorepo", "version": "1.0.0", "private": true, "type": "module", "scripts": { - "dev": "pnpm --filter volt dev", + "dev": "pnpm --filter voltx.js dev", "build": "pnpm -r build", - "preview": "pnpm --filter volt preview", + "preview": "pnpm --filter voltx.js preview", "test": "pnpm -r test", - "test:ui": "pnpm --filter volt test:ui", + "test:ui": "pnpm --filter voltx.js test:ui", "test:run": "pnpm -r test:run", "docs:dev": "pnpm --filter @volt/docs dev", "docs:build": "pnpm --filter @volt/docs build",