diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index aaa986f..a19e233 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,5 +1,14 @@ +import { readFileSync } from 'node:fs' +import { dirname, join } from 'node:path' +import { fileURLToPath } from 'node:url' + import { defineConfig } from 'vitepress' +const __dirname = dirname(fileURLToPath(import.meta.url)) +const pkg = JSON.parse(readFileSync(join(__dirname, '../../package.json'), 'utf-8')) as { + version: string +} + export default defineConfig({ title: 'Feel Your Protocol', description: 'Documentation for the Feel Your Protocol project', @@ -8,6 +17,7 @@ export default defineConfig({ nav: [ { text: 'Guide', link: '/guide/getting-started' }, { text: 'Contributing', link: '/contributing/how-to-contribute' }, + { text: 'Changelog', link: '/changelog' }, { text: 'Website', link: 'https://feelyourprotocol.org' }, ], sidebar: [ @@ -16,6 +26,7 @@ export default defineConfig({ items: [ { text: 'Getting Started', link: '/guide/getting-started' }, { text: 'Architecture', link: '/guide/architecture' }, + { text: 'Changelog', link: '/changelog' }, ], }, { @@ -34,14 +45,13 @@ export default defineConfig({ ], }, ], - socialLinks: [ - { icon: 'github', link: 'https://github.com/feelyourprotocol/website' }, - ], + socialLinks: [{ icon: 'github', link: 'https://github.com/feelyourprotocol/website' }], search: { provider: 'local', }, footer: { - message: 'This project and its documentation are under active development.', + message: `Structural base v${pkg.version} — latest docs always apply. See changelog for history.`, + copyright: 'Feel Your Protocol', }, }, }) diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 0000000..98d732e --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,52 @@ +# Changelog + +Structural-base history for Feel Your Protocol. The version tracks [`package.json`](https://github.com/feelyourprotocol/website/blob/main/package.json) — it reflects changes to the **contribution model, E-Components, and project structure**, not individual explorations. + +**Latest docs always apply.** There is no version switching; this page is a trail so you can follow along when the base evolves. + +## When the version bumps + +| Bump | When | +| ------------------- | ------------------------------------------------------------------------------------ | +| **Patch** (`0.1.x`) | E-Component APIs, contribution guides, architecture, or contributor workflow changed | +| **Minor** (`0.2.0`) | Breaking change to structural conventions (rare while in beta) | + +New explorations are listed under **Explorations** for visibility but do not drive version bumps. + +--- + +## [0.1.1] — 2026-06-08 + +### Added + +- **Bytecode Stepper E-Component** (`bytecodeStepperEC`) — documented building block for opcode/bytecode explorations +- **Docs changelog** (this page) +- E-Component **extension model**: layout slots, provide/inject context, companion components in the exploration folder + +### Changed + +- [E-Components](/contributing/e-components) — integration contract, extension points, composition direction +- [Available E-Components](/contributing/available-e-components) — equal-weight reference for all E-Components +- [Adding an Exploration](/contributing/adding-an-exploration) — building-block choice, extension guidance, E-Component test notes +- [Architecture](/guide/architecture) — E-Components described as a growing set, not precompile-only +- [AI-Assisted Development](/contributing/ai-assisted-development) — check Available E-Components first; slot/inject pitfall +- [UI Components](/contributing/ui-components) — placement rules aligned with exploration-folder companions + +### Explorations _(no version bump)_ + +- [EIP-8024](https://feelyourprotocol.org/eip-8024-stack-opcodes-dupn-swapn-exchange) — DUPN/SWAPN/EXCHANGE bytecode stepper (reference for E-Component + companion panel pattern) + +--- + +## [0.1.0] — 2026-05-01 + +Initial documented structural base (beta). + +### Added + +- Folder-per-exploration content model with dynamic routing via `REGISTRY.ts` +- Taxonomies: topics, timeline, tags +- **Precompile Interface E-Component** (`precompileInterfaceEC`) +- Shared UI components (`src/eComponents/ui/`) +- VitePress documentation site +- Contribution guides: adding explorations, styling, code conventions, third-party libraries diff --git a/docs/contributing/adding-an-exploration.md b/docs/contributing/adding-an-exploration.md index ddda8f8..0689308 100644 --- a/docs/contributing/adding-an-exploration.md +++ b/docs/contributing/adding-an-exploration.md @@ -12,7 +12,9 @@ src/explorations/eip-XXXX/ ├── MyC.vue # Interactive widget (required) ├── examples.ts # Example presets (recommended) ├── tests.spec.ts # Unit tests (required) -├── config.ts # Precompile config (for precompile explorations) +├── config.ts # E-Component config (when using an E-Component) +├── *.vue # Optional companion components +├── *.ts # Optional helpers (builders, domain logic) └── data/ # Optional data files ``` @@ -44,34 +46,29 @@ export const INFO: Exploration = { tags: [Tag.EVM, Tag.GasCosts], creatorName: 'YourName', creatorURL: 'https://x.com/YourHandle', - introText: - 'What does this change? ' + - 'A brief introduction to the protocol change.', - usageText: - 'Instructions on how to use the interactive widget below.', - poweredBy: [ - { name: 'EthereumJS', href: 'https://github.com/ethereumjs/ethereumjs-monorepo' }, - ], + introText: 'What does this change? ' + 'A brief introduction to the protocol change.', + usageText: 'Instructions on how to use the interactive widget below.', + poweredBy: [{ name: 'EthereumJS', href: 'https://github.com/ethereumjs/ethereumjs-monorepo' }], } ``` ### Field Reference -| Field | Required | Description | -|-------|----------|-------------| -| `id` | Yes | Unique identifier, matches the folder name | -| `path` | Yes | URL path for the exploration page | -| `title` | Yes | Display title | -| `infoURL` | Yes | Link to the specification or reference material | -| `topic` | Yes | Topic ID this exploration belongs to. Must be one of the fixed set: `scaling`, `privacy`, `ux`, `security`, `robustness`, `interoperability`. Topics are static and not added via contributions — see [Architecture](/guide/architecture#topics) for the full list. | -| `timeline` | Yes | Timeline ID for this exploration (e.g. `fusaka`, `glamsterdam`, `ready`, `research`, `ideas`). See [Architecture](/guide/architecture) for details. | -| `tags` | Yes | Array of `Tag` enum values (max 3–4). Tags are broader technical concepts that must be reusable across explorations. New tags can be proposed — see [Architecture](/guide/architecture#tags) for rules and the current list. | -| `image` | No | Imported image for topic overview display — see [Images](/contributing/images) for format, palette, and style guidance | -| `introText` | No | HTML-formatted introduction paragraph | -| `usageText` | No | HTML-formatted usage instructions | -| `creatorName` | No | Display name of the exploration's creator | -| `creatorURL` | No | URL to the creator's profile (X/Twitter, GitHub, etc.) | -| `poweredBy` | Yes | Array of `{ name, href }` for library credits | +| Field | Required | Description | +| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Yes | Unique identifier, matches the folder name | +| `path` | Yes | URL path for the exploration page | +| `title` | Yes | Display title | +| `infoURL` | Yes | Link to the specification or reference material | +| `topic` | Yes | Topic ID this exploration belongs to. Must be one of the fixed set: `scaling`, `privacy`, `ux`, `security`, `robustness`, `interoperability`. Topics are static and not added via contributions — see [Architecture](/guide/architecture#topics) for the full list. | +| `timeline` | Yes | Timeline ID for this exploration (e.g. `fusaka`, `glamsterdam`, `ready`, `research`, `ideas`). See [Architecture](/guide/architecture) for details. | +| `tags` | Yes | Array of `Tag` enum values (max 3–4). Tags are broader technical concepts that must be reusable across explorations. New tags can be proposed — see [Architecture](/guide/architecture#tags) for rules and the current list. | +| `image` | No | Imported image for topic overview display — see [Images](/contributing/images) for format, palette, and style guidance | +| `introText` | No | HTML-formatted introduction paragraph | +| `usageText` | No | HTML-formatted usage instructions | +| `creatorName` | No | Display name of the exploration's creator | +| `creatorURL` | No | URL to the creator's profile (X/Twitter, GitHub, etc.) | +| `poweredBy` | Yes | Array of `{ name, href }` for library credits | ## Step 3: Create `examples.ts` @@ -96,7 +93,16 @@ Each example has a `title` (displayed in the dropdown) and a `values` array (the ## Step 4: Create `MyC.vue` -This is your interactive widget. The approach depends on what you are building. +This is your interactive widget. Start by choosing a **building block**: + +| Approach | When to use | Docs | +| ----------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| **E-Component** | An existing E-Component matches your use case (precompile, bytecode stepping, …) | [Available E-Components](/contributing/available-e-components) | +| **Custom widget** | Unique behavior not covered by any E-Component | Option A below | + +Check [Available E-Components](/contributing/available-e-components) first — most explorations can be built by wiring a config, examples, and execution logic, often in under 30 lines. + +One primary E-Component per exploration is the supported path today. See [Composing E-Components](/contributing/e-components#composing-e-components) for the longer-term direction. ### Option A: Custom Widget @@ -145,7 +151,11 @@ await init() - + @@ -154,11 +164,13 @@ await init() The `ExplorationC` wrapper renders the title, info link, intro text, and usage text from your `info.ts`. You provide the interactive content via the `#content` slot. -### Option B: Precompile Interface E-Component +### Option B: E-Component + +When an existing E-Component fits, your `MyC.vue` wires config, examples, exploration metadata, and execution. Define the config in a separate `config.ts` file — this keeps it testable and separate from library setup. -If your exploration is about a precompile, you can use the Precompile Interface E-Component. It handles all input management while you provide the execution logic and result display: +#### Precompile explorations -First, define your precompile config in a separate `config.ts` file (this keeps the config testable): +If your exploration is about a precompile, use the Precompile Interface E-Component. It handles input management while you provide execution and result display: ```typescript // config.ts @@ -174,8 +186,6 @@ export const config: PrecompileConfig = { } ``` -Then in `MyC.vue`: - ```vue ``` +Define the config in a separate `config.ts` file: + +```typescript +import type { BytecodeStepperConfig } from '@/eComponents/bytecodeStepperEC/types' + +export const config: BytecodeStepperConfig = { + explorationId: 'eip-XXXX', + defaultExample: 'basic', +} +``` + +Example presets use `values[0]` as unprefixed hex bytecode. For programmatic bytecode construction, add helper modules in your exploration folder (see [EIP-8024 bytecode.ts](https://github.com/feelyourprotocol/website/blob/main/src/explorations/eip-8024/bytecode.ts)). + ### Component Props | Prop | Required | Description | @@ -294,10 +272,50 @@ interface BytecodeStepperConfig { ### Execution Modes -| Action | Behavior | -| --------- | ------------------------------------------------------------------------------ | -| **Run** | Execute bytecode to completion; record all step snapshots | -| **Step** | Advance one opcode (step mode is pre-armed when bytecode is valid) | -| **Reset** | Clear execution state, re-arm stepping; bytecode input is preserved | +| Action | Behavior | +| --------- | ------------------------------------------------------------------- | +| **Run** | Execute bytecode to completion; record all step snapshots | +| **Step** | Advance one opcode (step mode is pre-armed when bytecode is valid) | +| **Reset** | Clear execution state, re-arm stepping; bytecode input is preserved | Valid bytecode automatically enters step mode paused before the first opcode, so the first **Step** click executes that opcode. Changing bytecode triggers a full reset and re-arms stepping. + +### Extending Beyond the Core API + +#### `#below` Slot + +Render exploration-local companion components below the stepper UI: + +```vue + +``` + +#### `BYTECODE_STEPPER_CONTEXT` Inject + +Companion components can read live stepper state via Vue's provide/inject. Import the typed key from `bytecodeStepperContext.ts`: + +```typescript +import { inject } from 'vue' + +import { BYTECODE_STEPPER_CONTEXT } from '@/eComponents/bytecodeStepperEC/bytecodeStepperContext' + +const stepper = inject(BYTECODE_STEPPER_CONTEXT, null) +// stepper?.activeInstruction — current instruction row (or undefined) +// stepper?.mode — 'idle' | 'stepping' | 'running' | 'finished' | 'error' +// stepper?.bytecodeHex — current bytecode input +// stepper?.example — selected example key +``` + +::: warning Mount inside the slot tree +Provide/inject only works for **descendants** of the component that calls `provide`. Companion panels must be rendered inside the `#below` slot (or another slot on `BytecodeStepperEC`), not as a sibling placed next to it in `MyC.vue`. +::: + +For unit testing, companion components can accept the same values as optional props instead of relying on inject — see existing exploration panel tests for the pattern. + +Place domain-specific helpers, builders, and teaching UI in your exploration folder. Promote to shared code only when a second exploration needs the same pattern. diff --git a/docs/contributing/e-components.md b/docs/contributing/e-components.md index 2311faa..acec78c 100644 --- a/docs/contributing/e-components.md +++ b/docs/contributing/e-components.md @@ -2,10 +2,46 @@ **E-Components** are reusable, Ethereum-specific components that encapsulate common patterns across explorations. They live in `src/eComponents/` and are designed to let you build new explorations quickly without duplicating logic. -While the shared [UI components](/contributing/ui-components) (`src/eComponents/ui/`) provide generic building blocks like buttons and input fields, E-Components go a level higher: they package complete Ethereum-domain patterns — like a full precompile testing interface — into a single component with a clean configuration API. +While the shared [UI components](/contributing/ui-components) (`src/eComponents/ui/`) provide generic building blocks like buttons and input fields, E-Components go a level higher: they package complete Ethereum-domain patterns — precompile testing interfaces, bytecode steppers, and more — into components with a clean configuration API. For the list of ready-to-use E-Components, see [Available E-Components](/contributing/available-e-components). +## Integration Contract + +Each E-Component follows a shared integration model. Understanding this contract helps you wire explorations consistently and know where to add custom behavior. + +| Concern | Where it lives | Pattern | +| ---------------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | +| **Page chrome** | E-Component | Wraps `ExplorationC` (title, intro, examples, powered-by) | +| **Variation between explorations** | `config.ts` in the exploration folder | Typed config object, testable separately | +| **Library / execution ownership** | Exploration (`MyC.vue` and exploration-local modules) | Exploration creates EVM instances, `run` callbacks, or fork-specific setup; E-Component receives them as props | +| **Domain-specific visualization** | Exploration | Via **slots** or **companion components** wired into the E-Component | +| **Shared runtime state** | E-Component composable, optionally exposed via **provide/inject** | For panels that need live state without prop-drilling | + +### Standard Props + +Most E-Components accept a common set of props: + +| Prop | Description | +| ------------- | ---------------------------------------------------------------------- | +| `config` | Exploration-specific configuration (see the E-Component's config type) | +| `examples` | Example presets from the exploration's `examples.ts` | +| `exploration` | Metadata from the exploration's `info.ts` | + +Beyond these, E-Components accept props for **exploration-owned execution** — for example a `run` callback or a pre-configured EVM instance. E-Components do not import third-party libraries themselves; see [Third-Party Libraries](/contributing/third-party-libraries). + +### Extension Points + +E-Components deliberately cover **repeatable patterns**, not every pedagogical idea an exploration might need. When the core API is not enough, use the E-Component's extension hooks before wrapping or forking it: + +| Mechanism | Best for | Notes | +| -------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **Scoped slots** | Custom UI at a specific render point inside the E-Component | Slot props pass data back to the exploration (e.g. execution results) | +| **Named layout slots** | Additional panels or regions alongside the core UI | Mount exploration-local components inside the slot | +| **Provide/inject context** | Companion panels that react to live runtime state | Injection only works for **descendants** — extension UI must be mounted inside the E-Component's slot tree, not as a sibling next to it | + +Keep exploration-specific teaching UI, helpers, and domain logic in the **exploration folder**. Promote code to a shared utility or E-Component only when a second exploration needs the same thing. + ## How E-Components Work Each E-Component is a self-contained folder in `src/eComponents/` with a consistent internal structure: @@ -33,11 +69,27 @@ E-Component folders and files are post-fixed with **`EC`** (for E-Component): The typical pattern is: -1. Import the E-Component and its config type -2. Define a config object describing your specific use case -3. Render the component in your template with the config, examples, and exploration metadata +1. Check [Available E-Components](/contributing/available-e-components) for a matching building block +2. Define a `config.ts` describing your specific use case +3. Wire execution in `MyC.vue` (EVM setup, `run` function, etc.) +4. Render the E-Component with config, examples, and exploration metadata +5. Add exploration-local UI via slots or companion components if needed + +This keeps `MyC.vue` short and declarative — often under 30 lines for straightforward cases. See [Adding an Exploration](/contributing/adding-an-exploration) for the full walkthrough. + +## Composing E-Components + +Today, each major E-Component wraps the full exploration shell (`ExplorationC`). That means **one primary E-Component per exploration** is the supported, documented path. + +Exploration-specific additions compose _on top of_ that E-Component via slots and inject — not by nesting two full E-Components side by side. + +As the project grows, we expect explorations that combine capabilities from multiple E-Components (for example, a precompile comparison alongside a bytecode walkthrough). To prepare for that: + +- **E-Component authors** should separate "page chrome" from "capability" where feasible — sub-components that can be used standalone, not only as part of the full wrapper +- **Exploration authors** should keep custom additions local until a composition pattern is established project-wide +- **Future direction:** an exploration-level layout that owns `ExplorationC` once and hosts multiple E-Component fragments -This keeps your `MyC.vue` short and declarative — often under 30 lines. +If you are designing an E-Component or an exploration that might need multi-component composition, [open an issue](https://github.com/feelyourprotocol/website/issues) to discuss the approach before investing in a one-off structure. ## Creating a New E-Component @@ -48,7 +100,7 @@ If you spot a pattern shared across two or more explorations, it is a strong can 1. Create a folder in `src/eComponents/` following the naming convention: `EC/` 2. Define a `types.ts` with a configuration interface that captures the variation between use cases 3. Extract shared logic into a composable (`use.ts`) -4. Build the component(s) with a clean, props-based API +4. Build the component(s) following the [integration contract](#integration-contract) above 5. Document usage on the [Available E-Components](/contributing/available-e-components) page ### Design Principles @@ -57,9 +109,11 @@ A good E-Component should: - **Accept a config object** rather than many individual props — this keeps the consumer API minimal and easy to extend - **Provide sensible defaults** where possible, so simple use cases stay simple -- **Allow customization hooks** (callback functions in the config) for cases that need non-standard behavior -- **Keep the consumer's `MyC.vue` short and declarative** — ideally just a config + a single component tag -- **Encapsulate all state and logic** in a composable, keeping the Vue component focused on rendering +- **Expose clear extension hooks** — slots and/or typed inject context for exploration-local additions +- **Keep execution ownership in the exploration** — accept callbacks or library instances as props, never import third-party libraries directly +- **Keep the consumer's `MyC.vue` short and declarative** — ideally config + wiring + a single component tag +- **Encapsulate state and logic** in a composable, keeping the Vue component focused on rendering +- **Favor composable fragments** over monolithic widgets — sub-components usable on their own make future multi-E-Component explorations easier ### Ideas for Future E-Components diff --git a/docs/contributing/how-to-contribute.md b/docs/contributing/how-to-contribute.md index e4ef704..4c887c1 100644 --- a/docs/contributing/how-to-contribute.md +++ b/docs/contributing/how-to-contribute.md @@ -27,6 +27,8 @@ Fix typos, add guides, clarify explanations. Documentation lives in the `docs/` npm run docs:dev ``` +When a change affects the **structural base** (E-Components, contribution workflow, architecture), bump the patch version in `package.json` and add an entry to [Changelog](/changelog). New explorations alone do not require a version bump. + ### Report Issues Found a bug or have a suggestion? [Open an issue](https://github.com/feelyourprotocol/website/issues) on GitHub. Our issue templates will guide you through the relevant details. @@ -71,21 +73,22 @@ npm run test:e2e # E2E tests ## What Goes Where -| What you are working on | Where it lives | -|------------------------|----------------| -| A new exploration | `src/explorations//` | -| Exploration metadata | `src/explorations//info.ts` | -| Interactive widget | `src/explorations//MyC.vue` | -| Example presets | `src/explorations//examples.ts` | -| Exploration registry | `src/explorations/REGISTRY.ts` | -| E-Components | `src/eComponents/EC/` | -| Shared UI components | `src/eComponents/ui/` | -| Unit tests | `src/views/__tests__/` (or co-located `__tests__/`) | -| E2E tests | `cypress/e2e/` | -| Documentation | `docs/` | +| What you are working on | Where it lives | +| ----------------------- | --------------------------------------------------- | +| A new exploration | `src/explorations//` | +| Exploration metadata | `src/explorations//info.ts` | +| Interactive widget | `src/explorations//MyC.vue` | +| Example presets | `src/explorations//examples.ts` | +| Exploration registry | `src/explorations/REGISTRY.ts` | +| E-Components | `src/eComponents/EC/` | +| Shared UI components | `src/eComponents/ui/` | +| Unit tests | `src/views/__tests__/` (or co-located `__tests__/`) | +| E2E tests | `cypress/e2e/` | +| Documentation | `docs/` | ## Further Reading +- [Changelog](/changelog) — structural-base history (check after pulling `main`) - [AI-Assisted Development](/contributing/ai-assisted-development) — best practices for building explorations with AI agents - [Adding an Exploration](/contributing/adding-an-exploration) — step-by-step guide - [Using E-Components](/contributing/e-components) — reusable Ethereum-specific components diff --git a/docs/contributing/ui-components.md b/docs/contributing/ui-components.md index e0f8982..a70a8e0 100644 --- a/docs/contributing/ui-components.md +++ b/docs/contributing/ui-components.md @@ -1,6 +1,6 @@ # UI Components -The project provides a set of generic, reusable UI components that you can use in any exploration or E-Component. They live in `src/eComponents/ui/` and are already styled with the exploration design system — colors adapt automatically to the current topic. +The project provides a set of generic, reusable UI components that you can use in any exploration or E-Component. They live in `src/eComponents/ui/` and are already styled with the exploration design system — colors adapt automatically to the current topic. For the `e-*` CSS classes used in the examples below, see [Styling & Design](/contributing/styling). ## Where UI Components Live @@ -9,24 +9,23 @@ UI components are organized by scope: ``` src/eComponents/ ├── ui/ # Shared across all E-Components and explorations -│ ├── resultBox/ # Result display components +│ ├── resultBox/ │ │ └── ResultBoxUIC.vue │ ├── ExamplesUIC.vue │ ├── HexDataInputUIC.vue │ ├── ActionButtonUIC.vue │ ├── ButtonUIC.vue │ └── TooltipUIC.vue -└── precompileInterfaceEC/ - └── ui/ # (future) Components specific to this E-Component +└── EC/ # E-Component folders (optional local ui/ subfolder) ``` The placement rules: -| Scope | Location | Example | -|-------|----------|---------| -| Used across multiple E-Components or explorations | `src/eComponents/ui/` | `ResultBoxUIC`, `ExamplesUIC` | -| Specific to one E-Component | `src/eComponents//ui/` | (none yet) | -| Specific to one exploration | `src/explorations//custom/ui/` | (none yet) | +| Scope | Location | Example | +| ------------------------------------------------- | ------------------------------ | ------------------------------------------ | +| Used across multiple E-Components or explorations | `src/eComponents/ui/` | `ResultBoxUIC`, `ExamplesUIC` | +| Specific to one E-Component | `src/eComponents/EC/ui/` | (none yet) | +| Specific to one exploration | `src/explorations//` | Companion `.vue` files alongside `MyC.vue` | ## Available Components @@ -38,11 +37,11 @@ Example selector dropdown built on [Headless UI Listbox](https://headlessui.dev/ ``` -| Prop | Type | Description | -|------|------|-------------| -| `v-model` | `string` | Selected example key | -| `examples` | `Examples` | Object mapping keys to `{ title, values }` | -| `change` | `() => void` | Called when selection changes | +| Prop | Type | Description | +| ---------- | ------------ | ------------------------------------------ | +| `v-model` | `string` | Selected example key | +| `examples` | `Examples` | Object mapping keys to `{ title, values }` | +| `change` | `() => void` | Called when selection changes | ### HexDataInputUIC @@ -52,10 +51,10 @@ Hex data input textarea for raw byte input. ``` -| Prop | Type | Description | -|------|------|-------------| -| `v-model` | `string` | The hex data string | -| `rows` | `number` | Textarea row count | +| Prop | Type | Description | +| ------------ | ------------ | ---------------------- | +| `v-model` | `string` | The hex data string | +| `rows` | `number` | Textarea row count | | `formChange` | `() => void` | Called on input change | ### ResultBoxUIC @@ -68,12 +67,12 @@ Result display box with a title label. Used for showing computation output. Has ``` -| Prop | Type | Description | -|------|------|-------------| -| `title` | `string` | Title label shown in the box | -| `left` | `boolean` | Alignment: `true` for left, `false` for right | -| `infoText` | `string?` | Placeholder text shown when no content is available | -| `errorText` | `string?` | Error message (red) with a "Report on GitHub" hint | +| Prop | Type | Description | +| ----------- | ---------- | -------------------------------------------------------------- | +| `title` | `string` | Title label shown in the box | +| `left` | `boolean?` | Alignment: `true` for left, `false` for right (default: right) | +| `infoText` | `string?` | Placeholder text shown when no content is available | +| `errorText` | `string?` | Error message (red) with a "Report on GitHub" hint | `errorText` takes precedence over `infoText`. Both render below the slot content, so conditionally pass them only when the slot is empty: @@ -105,20 +104,25 @@ Async action button with loading state and tooltip. Disables itself and shows "L ``` -| Prop | Type | Description | -|------|------|-------------| -| `text` | `string` | Button label | -| `tooltip` | `string` | Tooltip text on hover | -| `onClick` | `() => Promise` | Async click handler | +| Prop | Type | Description | +| --------- | --------------------- | --------------------- | +| `text` | `string` | Button label | +| `tooltip` | `string` | Tooltip text on hover | +| `onClick` | `() => Promise` | Async click handler | ### ButtonUIC -Small icon button with tooltip. Used internally by `ExplorationC` for share and external-link icons. +Small icon button with tooltip. Used internally by `ExplorationC` for share and external-link icons. Wrap it in a clickable element when you need button behavior — the component itself renders the icon only. ```vue ``` +| Prop | Type | Description | +| --------- | ----------- | ------------------------------------------------------- | +| `icon` | `Component` | Vue component for the icon (e.g. from `@heroicons/vue`) | +| `tooltip` | `string?` | Tooltip text on hover | + ### TooltipUIC CSS tooltip wrapper. Used internally by `ButtonUIC` and `ActionButtonUIC`. You typically don't need this directly — use `ActionButtonUIC` or `ButtonUIC` instead. @@ -128,6 +132,7 @@ CSS tooltip wrapper. Used internally by `ButtonUIC` and `ActionButtonUIC`. You t Some UI components use [Headless UI](https://headlessui.dev/) (`@headlessui/vue`) — a set of completely unstyled, accessible UI primitives designed for Tailwind CSS. Headless UI handles keyboard navigation, focus management, and ARIA attributes while we control all styling via the exploration design system. Currently used by: + - `ExamplesUIC` — uses the Headless UI **Listbox** component As a contributor you don't need to interact with Headless UI directly — just use the UIC components as documented above. @@ -137,7 +142,8 @@ As a contributor you don't need to interact with Headless UI directly — just u All shared UI components use the `@/eComponents/ui/` path: ```typescript +import ActionButtonUIC from '@/eComponents/ui/ActionButtonUIC.vue' import ExamplesUIC from '@/eComponents/ui/ExamplesUIC.vue' +import HexDataInputUIC from '@/eComponents/ui/HexDataInputUIC.vue' import ResultBoxUIC from '@/eComponents/ui/resultBox/ResultBoxUIC.vue' -import ActionButtonUIC from '@/eComponents/ui/ActionButtonUIC.vue' ``` diff --git a/docs/guide/architecture.md b/docs/guide/architecture.md index 0598d4b..1071bc9 100644 --- a/docs/guide/architecture.md +++ b/docs/guide/architecture.md @@ -38,13 +38,13 @@ Topics are the high-level strategic pillars that group explorations by theme. Ea **Topics are a static, curated set — they are not meant to be added as part of regular contributions.** The current topics are: -| ID | Title | Description | -|----|-------|-------------| -| `scaling` | Scaling | Data availability, throughput, and L2 enablement | -| `privacy` | Privacy | ZK-proofs, homomorphic encryption, private mempools | -| `ux` | UX | Account abstraction, wallet infrastructure, signature schemes | -| `security` | Security | Validator incentives, cryptographic agility, MEV mitigations | -| `robustness` | Robustness | Gas cost accuracy, EVM semantics hardening, spec clarity | +| ID | Title | Description | +| ------------------ | ---------------- | ---------------------------------------------------------------------- | +| `scaling` | Scaling | Data availability, throughput, and L2 enablement | +| `privacy` | Privacy | ZK-proofs, homomorphic encryption, private mempools | +| `ux` | UX | Account abstraction, wallet infrastructure, signature schemes | +| `security` | Security | Validator incentives, cryptographic agility, MEV mitigations | +| `robustness` | Robustness | Gas cost accuracy, EVM semantics hardening, spec clarity | | `interoperability` | Interoperability | Cross-chain standards, bridge infrastructure, signature scheme support | When adding an exploration, pick the topic that best reflects the primary concern of the protocol change. @@ -61,45 +61,45 @@ Tags enrich navigation by adding broader Ethereum technical concepts, protocol-r **Tags grow with contributions** — unlike topics and timeline, new tags can be proposed when adding an exploration. They must follow these rules: -| Rule | Example | -|------|---------| -| Must be reusable beyond a single exploration | `EVM` ✅ — `EIP-7883` ❌ | -| Short form preferred | `EVM` ✅ — `Ethereum Virtual Machine` ❌ | -| No redundancy with existing tags | `Gas Costs` exists → don't add `Gas` | -| When in doubt, choose the more generic concept | `Gas Costs` ✅ — `Gas Increases` ❌ | +| Rule | Example | +| ---------------------------------------------- | ---------------------------------------- | +| Must be reusable beyond a single exploration | `EVM` ✅ — `EIP-7883` ❌ | +| Short form preferred | `EVM` ✅ — `Ethereum Virtual Machine` ❌ | +| No redundancy with existing tags | `Gas Costs` exists → don't add `Gas` | +| When in doubt, choose the more generic concept | `Gas Costs` ✅ — `Gas Increases` ❌ | **Format:** Enum keys use CamelCase (`GasCosts`), all-caps for abbreviations (`EVM`). Members must be sorted alphabetically (enforced by lint). ## E-Components -**E-Components** are reusable Ethereum-specific components that encapsulate common patterns across explorations. They live in `src/eComponents/` and follow a naming convention: folder and component names are post-fixed with `EC`. +**E-Components** are reusable Ethereum-specific components that encapsulate common exploration patterns. They live in `src/eComponents/` — one folder per pattern, with folder and component names post-fixed with `EC`. -The first E-Component is `precompileInterfaceEC`, which provides a complete precompile exploration interface — input parsing, hardfork comparison, result display — as a single component backed by a composable: +Each E-Component packages a recurring kind of interactive widget: page chrome (`ExplorationC`), example selection, domain-specific inputs, and shared state in a composable. The exploration wires it up via a typed `config.ts`, passes in execution (a `run` callback, an EVM instance, …), and adds exploration-local UI through slots or companion components when the core API is not enough. ``` -src/eComponents/precompileInterfaceEC/ -├── PrecompileInterfaceEC.vue # Full-featured precompile exploration template -├── PrecompileInterfaceResultEC.vue # Result display (pre/post hardfork comparison) -├── PrecompileValueInputEC.vue # Value input with byte length validation -├── usePrecompileState.ts # Composable: all state and logic -├── types.ts # PrecompileConfig and PrecompileValueDef interfaces -└── run.ts # EVM precompile execution utility +src/eComponents/EC/ +├── EC.vue # Main entry point +├── types.ts # Config interface +├── use.ts # Composable: state and logic +└── … # Sub-components and utilities as needed ``` -Using the Precompile Interface E-Component, a precompile exploration widget can be as short as 30 lines — just a config object and a single component tag. See [Using E-Components](/contributing/e-components) for details. +Examples in the codebase today include a **precompile testing interface** (`precompileInterfaceEC`) and a **bytecode stepper** (`bytecodeStepperEC`). More will follow as recurring patterns emerge — the set is meant to grow, not stay fixed on any one use case. + +For a typical E-Component-backed exploration, `MyC.vue` stays short: config, library setup, one component tag, and optional slot content. See [E-Components](/contributing/e-components) for the integration model and [Available E-Components](/contributing/available-e-components) for per-component API reference. ## UI Components Generic UI components live in `src/eComponents/ui/` alongside the E-Components they serve. These are reusable building blocks available for any exploration or E-Component: -| Component | Purpose | -|-----------|---------| -| `ExamplesUIC` | Example selector dropdown | -| `HexDataInputUIC` | Hex data input textarea | -| `ResultBoxUIC` | Result display box with title, info text, and error text | -| `ActionButtonUIC` | Async action button with loading state and tooltip | -| `ButtonUIC` | Icon button with tooltip | -| `TooltipUIC` | CSS tooltip wrapper | +| Component | Purpose | +| ----------------- | -------------------------------------------------------- | +| `ExamplesUIC` | Example selector dropdown | +| `HexDataInputUIC` | Hex data input textarea | +| `ResultBoxUIC` | Result display box with title, info text, and error text | +| `ActionButtonUIC` | Async action button with loading state and tooltip | +| `ButtonUIC` | Icon button with tooltip | +| `TooltipUIC` | CSS tooltip wrapper | Import them from `@/eComponents/ui/`: @@ -133,7 +133,7 @@ Each exploration is a separate chunk that is loaded on demand. Users only downlo ```typescript const componentModules = import.meta.glob('../explorations/*/MyC.vue') const ExplorationComponent = defineAsyncComponent( - componentModules[`../explorations/${explorationId}/MyC.vue`] + componentModules[`../explorations/${explorationId}/MyC.vue`], ) ``` diff --git a/docs/index.md b/docs/index.md index 5322483..4986a7e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,5 +28,5 @@ features: --- ::: warning Beta — Contributions Welcome! -This project is in **beta**. Everything works, but the APIs of reusable components (E-Components, shared UI) are still evolving. That means contributions may require some manual coordination during review until the interfaces fully stabilize — we are happy to guide you through! The fastest way to get started is to [add a new exploration](/contributing/adding-an-exploration). +This project is in **beta**. Everything works, but the APIs of reusable components (E-Components, shared UI) are still evolving. That means contributions may require some manual coordination during review until the interfaces fully stabilize — we are happy to guide you through! The fastest way to get started is to [add a new exploration](/contributing/adding-an-exploration). See the [changelog](/changelog) when the structural base moves forward. ::: diff --git a/package.json b/package.json index 523e02f..ca8dfe9 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "feelyourprotocol.org", - "version": "0.0.0", + "version": "0.1.1", "private": true, "type": "module", "engines": {