ShippedLarge

Add optional SynthJS runtime (dist/synth.js IIFE): data-synth-* open, dismiss, toggle, tabs, dropdown with ARIA, tests and AI contract

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

This is a thorough, well-structured delivery. The runtime is a dependency-free IIFE that implements all five behaviors with delegated listeners and per-element warnings. It ships with real-DOM happy-dom tests for every listed scenario, a contract generator built into the verifier, and full docs and showcase coverage. The main reservations are that no CI ran to confirm the tests pass, and that it adds an unrequested Node >=20 engine bump and a runtime-injected global `[hidden]` style rule.

Acceptance criteria · 6 of 7 met
  • YESBuild produces dist/synth.js as an IIFE defining window.Synth, no import/require, no new runtime deps`scripts/build.mjs` adds `SCRIPTS = { "synth.js": "js/synth.js" }`, and `build.test.mjs` asserts the IIFE shape, `window.Synth =`, the absence of import/require, and that `pkg.dependencies` is undefined.
  • YESNo bundler is added; only dev dependencies (happy-dom or jsdom)`package.json` adds only `devDependencies: { happy-dom }`, the build is a plain copy plus banner, and a test asserts happy-dom is the only dev dependency.
  • YESA page using only the CSS renders without errorsNo `src/*.css` files are changed, and the docs and components.md state that CSS-only pages keep working.
  • YESTests cover init, double init, dialog open/close/focus return, toggle incl. initial state, tabs click and keys, dropdown outside-click and Escape with focus return, dismiss in dialog and dismissible, missing target warns without throwing`scripts/synth-js.test.mjs` runs the built script in happy-dom via vm with real click and keydown events, and has a dedicated test for each listed case plus the Escape-in-dialog and showcase smoke tests.
  • YESsynthcss.ai.json has behaviors entries, minor version bumped, generated LLM contract includes a behavior sectionThere are behaviors on button, alert, nav and tabs and `contractVersion` goes 1.2.0→1.3.0. `verify-ai-contract.mjs` gains `renderBehaviors` and `--write`, `synthcss.llm.md` contains the generated "Behaviors (SynthJS)" section, and drift is tested.
  • YESDocs and showcase cover all five behaviorsThe new `docs/behaviors.md` covers intent, HTML, attributes, accessibility and misuse for each behavior plus an AI Behavior Reference table. `showcase/index.html` has a Behaviors section with five live demos that `check-showcase.mjs` enforces.
  • UNCLEARAll existing build and test commands passNo CI ran; the only evidence is the builder's statement that `npm test` passes with 115 tests.
Concerns
  • No CI checks ran on this commit, so the criterion "All existing build and test commands pass" rests only on the builder's claim of 115 passing tests. This matters more because the workflows now run `npm ci` for the first time.
  • `package.json` raises `engines.node` from >=18 to >=20 because happy-dom 20 needs it, and the README is updated to match. This drops Node 18 support for contributors, which the spec did not ask for. Separately, the committed `package-lock.json` root entry still says `"node": ">=18"`, so the lockfile was not regenerated after the engines change.
  • At init, `src/js/synth.js` injects a global `<style data-synth>` containing `[hidden]:not([hidden="until-found"]) { display: none !important; }`. It is documented and pragmatic, since `.alert`, `.nav` and `.stack` set `display`. But it is page-wide CSS added by the runtime and will override any author rule that intentionally styles `[hidden]` elements.
  • Elements are marked ready once and never re-checked. If tabs are added to an existing `[data-synth-tabs]` container, or a dropdown menu is added later, a further `Synth.init()` call will not set their initial roving tabindex or `aria-expanded`. Click and keyboard handling still works because it is delegated.
  • The dialog focus-return test closes the dialog with `dialog.close()` rather than a real Escape keydown, so native Escape behavior is assumed, not exercised. The double-init test likewise counts calls by monkeypatching `showModal` and `focus`, which is acceptable but indirect.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.29, counted as builder cost.

Motivation

AI-generated interfaces built with SynthCSS currently need hand-written DOM event code for interactivity. SynthJS is an optional, dependency-free runtime in the same repo. Markup declares interaction intent with data-synth-* attributes and SynthJS implements it accessibly. CSS-only usage stays fully supported.

Scope

1. Source and build

  • Source lives under the existing source layout (e.g. src/js/synth.js). Do not restructure existing CSS paths.
  • The existing lightweight build scripts emit dist/synth.js: a plain, browser-compatible IIFE exposing window.Synth, with no import/require and no runtime dependencies.
  • No bundler (esbuild, rollup, etc.) is added. The script copies the file and optionally minifies it if the repo already has a minify step.
  • dist/synth.css is unchanged. Non-interactive components need no JS.

2. Behaviors (one attribute per intent, no aliases)

Open (dialog): data-synth-open="<id>" on a button calls showModal() on the target <dialog>. Escape closes it natively. On close, focus returns to the opener.

Dismiss: data-synth-dismiss on a button closes the closest <dialog> if inside one. Otherwise it hides the closest [data-synth-dismissible] ancestor (e.g. an .alert).

  • Assumption: hiding means setting the hidden attribute, not removing the element.

Toggle: data-synth-toggle="<id>" on a button toggles hidden on the target.

  • It sets aria-controls if missing and keeps aria-expanded in sync.
  • Initial aria-expanded is derived from the target's hidden state at init.
  • data-synth-collapse is not added. Collapse is a use case of toggle.

Tabs: data-synth-tabs goes on a container (reusing the existing .tabs / .tabs-item markup and its ARIA-driven CSS state). Its role="tab" buttons reference role="tabpanel" elements via aria-controls.

  • Click selects a tab: sets aria-selected, roving tabindex (0 on the selected tab, -1 on others), and hidden on non-selected panels.
  • ArrowLeft/ArrowRight (wrapping), Home and End move focus and selection.

Dropdown: data-synth-dropdown goes on a wrapper containing a trigger button and a menu element.

  • Clicking the trigger toggles the menu's hidden and the trigger's aria-expanded.
  • Outside click and Escape close the menu. Escape returns focus to the trigger.
  • Reuse existing nav-related markup where it fits. Otherwise add only the minimal data-synth-* and ARIA structure.
  • Assumption: the trigger is identified as [data-synth-dropdown-trigger] or the first button, and the menu as [data-synth-dropdown-menu] or [role=menu].
  • No new visual component API or class names beyond what is strictly required.

3. Lifecycle

  • Auto-initializes on DOMContentLoaded, or immediately if document.readyState is not loading.
  • Synth.init(root = document) initializes markup inserted later.
  • Repeated calls must not double-bind. Use a per-element marker or delegated listeners.
  • A missing or invalid target logs one console.warn per element and never throws.

4. AI contract

  • Extend synthcss.ai.json with behaviors entries on the relevant components. Each entry has: intent, attribute, target type, requiredMarkup, and accessibility expectations.
  • The existing LLM contract generator emits a behavior section from this data. No separate hand-written registry.
  • Bump the contract minor version (e.g. 1.1.0 → 1.2.0) and update any changelog the repo keeps.

5. Docs and showcase

  • Document each behavior with: intent, minimal HTML, attributes, accessibility behavior, and common misuse.
  • Add a compact AI behavior reference.
  • The showcase gets live examples of dialog, toggle, tabs, dropdown and dismissible alert, loading the repo's dist/synth.js or its source.

6. Tests

  • Add happy-dom or jsdom as a devDependency only. Use a real DOM and real events, not a hand-written fake.
  • Integrate with the existing test command.

Acceptance criteria

  • The build produces dist/synth.js as an IIFE defining window.Synth, with no import/require statements and no new runtime dependencies in package.json.
  • No bundler is added. Only dev dependencies are added (happy-dom or jsdom).
  • A page using only dist/synth.css renders without errors.
  • Tests cover:
    • initialization
    • double Synth.init() with handlers firing exactly once
    • dialog open, close and focus return
    • toggle (hidden and aria-expanded, including the initial state)
    • tab click and Arrow/Home/End keys (aria-selected, tabindex, panel hidden)
    • dropdown outside-click and Escape (with focus return)
    • dismiss in a dialog and in a [data-synth-dismissible]
    • a missing target warns without throwing
  • synthcss.ai.json contains behaviors entries, its minor version is bumped, and the generated LLM contract includes a behavior section.
  • Docs and showcase cover all five behaviors.
  • All existing build and test commands pass.

Out of scope

  • State management, routing, data fetching, form frameworks
  • Framework adapters
  • Drag and drop, rich text
  • Animation systems
  • Focus-trap polyfills beyond native <dialog>
  • Dropdown positioning engines
  • Bundler adoption
  • A data-synth-collapse alias

No comments yet.