tobogganSe connecter

library

Prebuilt pebble components: drop-in custom elements, no compiler needed

Clone avec HTTPS, un jeton personnel en mot de passe, ou avec SSH, une clé ajoutée dans vos paramètres.

Dernier runAucun
0Étoiles
0Forks
2Issues
NomDernier commitDate
docs/sequence 0.1.0: <pebble-sequence>, a sequence of steps edited as a tree of cardsil y a 4 j
examples/sequence 0.1.0: <pebble-sequence>, a sequence of steps edited as a tree of cardsil y a 4 j
packages/sequence 0.1.1: its styles apply (unscoped, as more and combobox)il y a 4 j
plugins/Merge library-tablet: the CodeMirror notes editor, <pebble-tablet>il y a 3 sem.
scripts/A package ships only the declarations its index reachesil y a 3 sem.
test/Merge pull request #9 from ask/query-pebble-consumeril y a 22 h
.gitignoreMerge library-scaffold: the library toolchainil y a 3 sem.
bun.lockMerge pull request #9 from ask/query-pebble-consumeril y a 22 h
bunfig.tomlpebble comes from the registry: the exact 0.1.0 pinil y a 3 sem.
package.jsonMerge pull request #9 from ask/query-pebble-consumeril y a 22 h
README.mdMerge pull request #9 from ask/query-pebble-consumeril y a 22 h
tsconfig.build.jsonMerge library-scaffold: the library toolchainil y a 3 sem.
tsconfig.jsonMerge library-docs: library README, toaster docs, consuming, toaster smokeil y a 3 sem.
README.MD

pebble/library

Prebuilt pebble components: drop-in custom elements, no compiler needed.

Each package in packages/ builds a self-contained dist — bundle, types, stylesheet — that a consumer vendors or loads with a <script type="module"> tag. pebble is bundled in: there is no JSX compiler and no pebble build step on the consumer's side. The import IS the registration.

Components

  • toaster — <pebble-toaster>: toast announcements, polite and assertive channels. docs/toaster.md
  • timeline — <pebble-timeline>: phases on a shared time axis, one lane per track, drawn from the server's <table>, which stays the data of record. docs/timeline.md
  • tablet — <pebble-tablet>: a notes editor on its own pebble-native engine, plain text or a page-defined dialect (commands, a decorated backdrop, task boxes); the <textarea> stays the surface and the form field of record. 10.0 kB gz. docs/tablet.md
  • vote — <pebble-vote>: an up/down vote over the server's two forms, painted at once, posted with fetch and reconciled with the server's tally; a captcha falls back to the native post. docs/vote.md
  • more — <pebble-more>: a feed's "load more" link that loads the next page's items into the list as it nears the viewport; the link stays the no-JS path. docs/more.md
  • lite-youtube — <pebble-lite-youtube>: a YouTube poster link that becomes the privacy-enhanced player on activation; nothing loads from YouTube before. docs/lite-youtube.md
  • combobox — <pebble-combobox>: suggestions under a search form's field as the reader types, from the server's HTML, with the ARIA combobox pattern; the form stays a plain GET search. docs/combobox.md
  • sequence — <pebble-sequence>: a sequence of steps edited as a tree of cards — linear runs, branching steps split into outcomes — with the page's kinds and fields; a <textarea> of JSON stays the form field of record. docs/sequence.md

Using a component

Vendor the dist (the flow today — docs/consuming.md):

<script type="module" src="vendor/pebble-library/toaster.js"></script>
<pebble-toaster></pebble-toaster>

or import it from your own module graph — a plain ESM file, side effect and all:

import "./vendor/pebble-library/toaster.js";

Installed as a package (the registry flow, once published), the same import by name:

import "@pebble/toaster";

The element registers itself; there is nothing else to import and nothing to compile. Importing twice is safe: a second bundle carrying the component gets the first's constructor back.

Size

Whole-bundle numbers from bun run sizes (the release pipeline: Bun bundle + minify, then a Terser internal-property pass), budgets enforced in test/size.test.ts:

componentgzipbrotliΔ over floor
floor (an empty component: shell + runtime + signals)4020 B3618 B—
combobox6627 B5988 B2607 B
sequence11391 B10301 B7371 B
lite-youtube5049 B4469 B1029 B
more5728 B5121 B1708 B
timeline12273 B10961 B8253 B
toaster8513 B7639 B4493 B
vote6023 B5393 B2003 B

tablet: engine rewrite in flight; its size row lands with it.

The floor is one-time runtime cost, shared by every component on the page; the Δ is what a component itself adds.

The pebble dependency

The framework comes from the forge's npm registry as an exact pin, "@pebble/pebble": "0.2.1", with the @pebble scope mapped in bunfig.toml (the token is $TOBOGGAN_TOKEN, never a literal). Exact pins, never ranges; a bump is its own commit. Consumers of the library never install pebble: it is bundled into each dist/<name>.js.

The library compiles its JSX through pebble's consumer compiler, @pebble/pebble/plugin (the test preload in plugins/preload.ts, the build, the size script). Since 0.2.0 the compiler's Babel packages are optional peers of pebble, needed only by that entry, so the library pins them itself as exact dev dependencies at the versions pebble names: @babel/core 7.29.7, @babel/preset-typescript 7.29.7, babel-plugin-jsx-dom-expressions 0.40.10. Bump them with pebble.

For a dev loop against an unpublished pebble, "@pebble/pebble": "file:../pebble/dist" works as a local override (pebble's dist is its published face; bun run sync-pebble prepares it). Never commit it.

Contributing

TOBOGGAN_TOKEN=… bun install   # the @pebble scope needs the registry token
bun test              # happy-dom + the consumer compiler — the consumer's path
bun run typecheck     # tsc --noEmit
bun run build         # per-package dists in dist/
bun run sizes         # the release-size table; budgets in test/size.test.ts
bun run smoke         # dist/toaster.js on real headless Chromium (build first)

With the file: override in an OpenCode worktree (.worktrees/<name>), run bun run sync-pebble before the first bun install — it symlinks ../pebble so the file: dependency resolves. If bun test fails with a CSS compile error naming a worktree that no longer exists, the staleness is bun's transpiler cache, not the tree: delete the offending entries under ~/.bun/install/cache (or the whole cache) and re-run.

Rules that bite, from the pebble repo:

  • Workspace packages use workspace:*, never file:.
  • Build entrypoints are shims generated into .build/, never a package's own index (Bun elides the graph of an entrypoint that lives inside the package it builds).
  • Never _$-prefix a property on a Symbol.for record — the Terser pass mangles _$ names per build, and those records cross build boundaries.
  • Component packages do not set sideEffects: false — the import IS the registration. scripts/build.ts refuses to build one that does.

Adding a component

packages/<name>/package.json   "@pebble/<name>", type: module, exports: { ".": "./index.ts" }
packages/<name>/index.ts(x)    self-registering: define("<tag>", …)
packages/<name>/<name>.css     optional: also shipped raw as dist/<name>.css

bun run build picks it up → dist/<name>.js + dist/<name>.d.ts (+ dist/<name>.css). Then add its row to test/size.test.ts: the measured size + ~15%.

Docs

docs/