boxel-patterns

Files (124)

• SKILL.md
• README.md · patterns/app-card-home-with-search/
• README.md · patterns/attach-remote-image/
• README.md · patterns/automate-declared-captures/
• example.gts · patterns/automate-declared-captures/
• README.md · patterns/automate-image-steering/
• example.gts · patterns/automate-image-steering/
• README.md · patterns/automate-linked-to-me-lookup/
• example.gts · patterns/automate-linked-to-me-lookup/
• README.md · patterns/automate-run-command-cli/
• example.gts · patterns/automate-run-command-cli/
• README.md · patterns/build-planning-cards-trio/
• README.md · patterns/build-site-config-with-theme/
• example.gts · patterns/build-site-config-with-theme/
• README.md · patterns/cardinfo-override-title/
• example.gts · patterns/cardinfo-override-title/
• README.md · patterns/collab-yjs-shared-document/
• README.md · patterns/command-atomic-install/
• example.gts · patterns/command-atomic-install/
• README.md · patterns/command-data-resource/
• example.gts · patterns/command-data-resource/
• README.md · patterns/command-optimistic-pipeline/
• example.gts · patterns/command-optimistic-pipeline/
• README.md · patterns/command-typed-with-progress/
• example.gts · patterns/command-typed-with-progress/
• README.md · patterns/command-with-skill-card-ref/
• example.gts · patterns/command-with-skill-card-ref/
• README.md · patterns/containsmany-sorted-render/
• example.gts · patterns/containsmany-sorted-render/
• README.md · patterns/format-morph-shared-component/
• README.md · patterns/integrate-capture-card-format/
• example.gts · patterns/integrate-capture-card-format/
• README.md · patterns/integrate-chess-js-via-cdn/
• example.gts · patterns/integrate-chess-js-via-cdn/
• README.md · patterns/integrate-filedef-generated-image/
• example.gts · patterns/integrate-filedef-generated-image/
• README.md · patterns/integrate-leaflet-via-cdn/
• example.gts · patterns/integrate-leaflet-via-cdn/
• README.md · patterns/integrate-one-shot-llm/
• example.gts · patterns/integrate-one-shot-llm/
• README.md · patterns/integrate-openrouter-image-generation/
• example.gts · patterns/integrate-openrouter-image-generation/
• README.md · patterns/integrate-send-request-via-proxy/
• example.gts · patterns/integrate-send-request-via-proxy/
• README.md · patterns/integrate-three-js-3mf-fabrication/
• example.gts · patterns/integrate-three-js-3mf-fabrication/
• README.md · patterns/integrate-three-js-via-cdn/
• example.gts · patterns/integrate-three-js-via-cdn/
• README.md · patterns/integrate-thumbnail-card-ai/
• example.gts · patterns/integrate-thumbnail-card-ai/
• README.md · patterns/integrate-tone-js-via-cdn/
• example.gts · patterns/integrate-tone-js-via-cdn/
• README.md · patterns/integrate-web-audio-synthesis/
• example.gts · patterns/integrate-web-audio-synthesis/
• README.md · patterns/layout-3d-card-carousel/
• example.gts · patterns/layout-3d-card-carousel/
• README.md · patterns/layout-design-board/
• example.gts · patterns/layout-design-board/
• README.md · patterns/layout-kanban-drag-drop/
• example.gts · patterns/layout-kanban-drag-drop/
• …and 64 more

SKILL.md (first lines)

# Boxel Patterns

The curated `boxel` skill and its siblings teach you **how the framework works**. This skill catalogues **what people have built with it** — distilled patterns extracted from real working realms, each with a minimal `example.gts` you can adapt.

Patterns are indexed by **user intent**, not by class hierarchy. Find the pattern that matches the outcome the user described, then read its `README.md` + `example.gts`.

---

## How to use this skill

1. Translate the user's request into an outcome (one of the intent groups in **Ready Patterns** below).
2. Search **Ready Patterns** first — these are the ones with working `example.gts` files.
3. Read `patterns/<slug>/README.md` for when/why/insight/gotchas, then `patterns/<slug>/example.gts` for the code.
4. Adapt to the user's domain. Examples are reduced to pattern essence — names, data, and styling will need replacement.
5. If nothing matches, see **Source Realm Fallbacks** at the bottom, or fall back to the core skills (`boxel`, `boxel-design`, `boxel-ui-guidelines`). A reserved-but-unextracted slug list lives in `references/pattern-backlog.md` — **do not chase planned patterns**; fall back to core skills instead.

**Adding or promoting a pattern?** The folder shape, README template, naming conventions, `validated:` ladder, promotion bar, and host-command audit all live in `references/pattern-authoring.md`. Read it before touching the tree.

---

## Ready Patterns

Ready patterns below can be read and adapted. Each has `patterns/<slug>/README.md`; most also have a separate `patterns/<slug>/example.gts`. A few are README-with-inline-recipe — the worked code lives in fenced blocks inside the README itself, marked `(README-only)` in the list below.

> **Start here for any new card:** `theme-first-workflow` + `cardinfo-override-title` together form the recommended "step 0" for every new CardDef. The theme workflow decides whether Boxel defaults are sufficient or a specific Theme is wanted; it does not require a Theme link. Skipping these decisions is the most common cause of cards that "look wrong" or have blank titles.

### Show

- **`app-card-home-with-search`** *(README-only)* — The home CardDef for any card family: `prefersWideFormat = true` + one `@context.searchResultsComponent` section per CardDef, live-updating. **Build this whenever you build 2+ related CardDefs.**
- `show-card-list-with-views` — Generic CardsGrid that takes `Query` + realms + a view name (`card` / `strip` / `grid`) and renders via `@context.searchResultsComponent` (entry-rooted, live by default). The lower-level building block used inside `app-card-home-with-search`.
- **`show-list-prefer-prerendered`** — The cost decision for any card that *lists* cards: render the cheap prerendered `@context.searchResultsComponent` stream, and reserve the instance-hydrating getters (`getCards` / `getCardCollection` / `store.search`) for rows you genuinely read or mutate — scoped to the current realm. Read this before writing the query for a browse/feed/roster view.
- `show-count-tiles-from-query` — Dashboard count tiles that issue `page: { size: 1 }` queries and read `results.meta.page.total` from `@context.searchResultsComponent` (with `@mode='none'`, since only the count is needed). Use for overview badges, operational signals, inbox counts, and clickable dashboard sections without rendering every matching card.
- `show-table-from-query` — Reusable table that takes a `Query` + realm and renders any cards-of-type as sortable rows. WeakMap field-component caching.
- `show-runtime-markdown-html` — Render BFM/markdown to HTML at runtime in `isolated`/`embedded` templates via MarkdownField + `<@fields.body />`.
- `show-wiki-links` — Turn `[[Page Name]]` text inside rendered MarkdownField output into clickable links that resolve against a self-referential `relatedPages = linksToMany(() => WikiPage)` relationship and call `viewCard`.
- `show-filedef-audio-player` — Durable audio playback from a realm MP3/WAV/OGG file using `linksTo(FileDef)` and optional `linksTo(ImageDef)` cover art. Use this instead of storing `blob:`, `data:`, base64, or MP3 bytes in card JSON; source is the A Million Dreams FileDef audio example.
- `show-pdf-annotations-filedef` — PDF.js viewer/annotation pattern updated for FileDef-backed PDFs: `linksTo(FileDef)` for the `.pdf`, CDN PDF.js worker setup, text-layer selection, and normalized highlight bounds in `annotationData`.

### Pick / Input

- `pick-rating` — Editable star-rating FieldDef with full/half/empty read display, atom + embedded formats, and `@set(new RatingsSummary(...))` writeback.
- `pick-typed-sort` — `SortMenu` dropdown + typed `SortOption` interface + exported `Sort` constants. Replaces ad-hoc string sort keys.
- `attach-remote-image` *(README-only)* — Image field accepting an uploaded ImageDef OR an external URL via the pair-of-fields convention (`linksTo(ImageDef)` + URL field). **Critical:** prevents the realm-bricking external-URL-in-`links.self` bug (Cardinal Rule 12). See `boxel/references/base-field-catalog.md` "Image fields — the URL/ImageDef pair pattern".

### Build / Template

- **`build-planning-cards-trio`** *(README-only)* — Stage-0 planning artifacts for any card family: three CardDefs (`ArchitecturePlan`, `DataModelPlan`, `MicroMockups`) whose `static isolated` templates ARE the plan documents. Without stage 0, fitted views come out pedestrian. See `boxel/references/design-playbook.md` "Planning before code — Stage 0".
- **`theme-first-workflow`** — Decide whether Boxel defaults are sufficient or a specific Theme is wanted BEFORE writing the card. Link via `cardInfo.theme` only for the latter; templates reference theme tokens (`var(--background)`, `var(--primary)`, etc.) from line one. The starting step for any new card or app.
- **`cardinfo-override-title`** — Override `cardTitle` to respect `cardInfo.name` first, then fall back to a primary field (`headline`, `firstName + lastName`, etc.), then to the default. Every CardDef with a natural identifier needs this.
- `build-site-config-with-theme` — Multi-page site registry: `SiteConfig` links to a `ThemeCard` brand guide and `linksToMany(PageConfig)` nav entries; page shells compute `cardTheme` from the site unless overridden by `cardInfo.theme`.
- `containsmany-sorted-render` — Render a `containsMany`/`linksToMany` in a non-insertion order without losing the host's field rendering chrome. Sort indexes in the Component, drive `{{#each}}` with `<@fields.notes.[i] />`.
- `format-morph-shared-component` *(README-only)* — Assign one Glimmer Component to both `static isolated` and `static edit` so the component stays mounted across format flips. CSS transitions on `.card--{{@format}}` morph the visual without remount. Token-efficiency win when isolated and edit are layout variants of the same content.
- `polymorphic-field-subclass` *(README-only)* — A `contains(Shape)` slot that holds any subclass of `Shape` (Circle, Square, Triangle). Swap by assigning `new Circle({})` to the model field — first-class, type-safe, persistable. Replaces `(model as any).field = value` hacks.

### Automate / Compute

- `automate-linked-to-me-lookup` — Schema-level query-backed `linksToMany` (preferred) OR component-level `getCards()` to materialize inbound references. Two signatures documented.
- **`resource-consume-from-context`** — How to read what `@context.getCards` / `getCard` / `getCardCollection` hand back: they are resources, not promises. Hold one as a class field and render straight off `instances` / `card` / `cards`, gated on `isLoading` / `isLoaded` and the error properties. Carries the smell list to check card code against — awaiting a resource, `.then` on one, copying `.instances` into `@tracked`, polling one on a timer, reading one from a constructor. **Read this before writing any code that consumes one of the three getters.**
- `resource-for-state` *(README-only)* — Wrap third-party library state, legacy kanban column ordering, or any "stateful object that re-runs when args change" in an `ember-modify-based-class-resource` Resource. Used by older `kanban-resource.gts` (DndColumn ordering) and `chess-game.gts` (chess.js wrapper). New kanban boards should use `layout-kanban-drag-drop`.
- **`automate-declared-captures`** — Self-refreshing capture slots declared as `static captures` on a CardDef/FileDef: captured server-side on every index, consumed via the reserved `@model.captureURLs.<name>` getter, and (with `useAsThumbnail: true`) feeding `cardThumbnailURL` so grid tiles show the card's **real rendering with zero template edits**. Use for automatic thumbnails, social/og images, and media poster frames. Prefer this over the imperative siblings whenever the card should *always* have a current picture of itself.
- `automate-image-steering` — Steerable image generator: immutable seed prompt + latest steering command + image lineage attached to OpenRouter multimodal calls, so iterative refinement doesn't lose subject identity. Includes `imageHistory`/`firstImage` pinning and `restartableTask` cancellation.

### Layout

- `layout-design-board` — Parent card = layout shell; each `linksTo` child renders at a chosen format. Includes the chrome-strip CSS trick.
- `layout-kanban-drag-drop` — Persistent kanban board using `KanbanPlane` from `@cardstack/boxel-ui/components`: columns + placements data model, fitted child cards, pointer/keyboard drag, ghost/insertion behavior, hidden columns, and WIP limits.
- `layout-3d-card-carousel` — `@context.searchResultsComponent` (`@overlays={{false}}`) + CSS `perspective` + per-card `--card-index` / `--total-cards` CSS vars for a circular 3D arrangement. Auto-rotate, hover lift, filter-state reactive. The 3D-hero alternative to a flat grid.
- `layout-sectioned-record-with-nav` — Long-record card with sticky 220px left nav rail (one button per section, click-to-scroll, active-section highlight) + main content stack of `<@fields.<section> @format='embedded' />`. Pairs with `organize-sensitive-stub-pair` for record/stub apps. Requires `prefersWideFormat = true`.

### Link / Navigate

- `link-discriminated-action-resolver` — Type-safe action menu that adapts to which CardDef subtype you have. Adapter classes per subtype + conditional spread for optional actions.
- `link-element-tag-helper` — Dynamic HTML tag via the `element` helper from `@cardstack/boxel-ui/helpers`.
- `link-onclick-outside` — Canonical `onClickOutside` modifier (50ms-delayed mousedown listener) for popovers and inline editors.
- `link-view-transition` — `document.startViewTransition` + `view-transition-name` for free morph animations between DOM states. Add/remove items, format flips, list reorders, slide-deck auto-animate. Feature-detect for older browsers.
- `link-flip-card` — CSS-only front/back flip primitive: `perspective` + `transform: rotateY(180deg)` + `backface-visibility: hidden`, driven by a single `@tracked isFlipped`. Flashcards, product reveals, two-sided info cards.
- `link-host-mode-paths` — Route clean external URLs (`/`, `/about`, `/pricing`) to specific cards via `hostRoutingRules` on the `RealmConfig` card at `/realm.json`. Public realms only; static paths only; same-realm references.

### Collaborate

- `collab-yjs-shared-document` *(README-only)* — Real-time co-editing of a card-backed document (Y.Text code/text pad, or Y.Map structured state like a shared 3D scene) via a Yjs websocket relay. Everyone syncs; a single committer peer holding a realm JWT materializes settled content back into the official card. Includes the seeding rules, read-only role enforcement, and the boundary with ordered commands (scarcity/fairness never goes in a CRDT).

### Integrate external

- `integrate-openrouter-image-generation` — Preferred image generator. OpenRouter chat completions with `modalities: ['image', 'text']`; default to Gemini image, use ChatGPT/OpenAI image models when requested; persist bytes with `WriteBinaryFileCommand` + `ImageDef`.
- `integrate-one-shot-llm` — Single LLM call via `OneShotLlmRequestCommand` (OpenRouter). System + user prompt + model id → output.
- `integrate-filedef-generated-image` — Write generated image bytes with `WriteBinaryFileCommand`, then link `ImageDef` / `PngDef`.
- `integrate-capture-card-format` — `CaptureTool` captures a **settled PNG of any saved card at `isolated` or `embedded` format** (Puppeteer-driven through the prerender pool) and returns a durable served media-cache URL; nothing is written into a realm and only read access is needed. Use for **point-in-time** snapshots you keep a URL to: documentation, audit/before-after trails. The same pipeline exports a **paged PDF** — pass `type: 'pdf'` to the tool, or compose a durable `_capture/…?type=pdf` URL (add `media=print` for the card's `@page`/print CSS) for a printable, always-current document (invoice/report/statement), and render it through the host's `SignedCaptureLink`/`SignedCapture` components so private-realm downloads and `<object>` embeds authorize (`@download`/`@filename` save the file under a chosen name). For a card that should *always* carry a current picture of itself (thumbnails, og images), use `automate-declared-captures` instead.
- `integrate-thumbnail-card-ai` — `GenerateThumbnailCommand` generates an **AI thumbnail** via OpenRouter, writes it to a realm, and optionally auto-patches `cardInfo.cardThumbnail` in one call. Use when you want a *designed representation* of a card rather than its actual rendering; composes with `link-command-menu-item` for one-click menu actions.
- `integrate-send-request-via-proxy` — Third-party HTTP that needs a key the realm server holds, through the host proxy; public, CORS-open APIs use plain `fetch` (rules in the pattern).
- `integrate-three-js-via-cdn` — Three.js inside a card via ESM CDN. Lifecycle-managed via Glimmer modifier with explicit cleanup. Same modifier shape covers Babylon.js and raw WebGL shaders.
- `integrate-three-js-3mf-fabrication` — Raised relief versus flat/flush inlay geometry, cavity overtravel, positive-scale extrusion, welded manifold meshes, and color-mapped component assemblies for 3MF slicers.
- `integrate-leaflet-via-cdn` — Leaflet map inside a card. Requires CSS link + explicit container size.
- `integrate-chess-js-via-cdn` — chess.js engine + cm-chessboard renderer combo. FEN persistence.
- `integrate-tone-js-via-cdn` — Tone.js music toolkit inside a card via `<script>`-tag CDN load. Polyphonic synths, transports, sequences, effects chains. Same lifecycle shape as `integrate-three-js-via-cdn`.
- `integrate-web-audio-synthesis` — Raw `AudioContext` for synthesized tones, drums, and UI sound feedback. No library load. Module-singleton context + oscillator + gain envelope; ships click / success / error presets.

### Make a Command

- `command-data-resource` — Call a host Command reactively from a Glimmer component via `commandData<T>`. Replaces manual `restartableTask` + `@tracked` plumbing.
- `command-with-skill-card-ref` — Card kicks off an AI conversation: skill-card URL via `import.meta.url`, attached cards, `UseAiAssistantCommand` from `@cardstack/boxel-host/tools/ai-assistant`.
- `command-typed-with-progress` — `Command<Input, Output>` with a typed `progressStep` state machine the invoking component reflects in UI.
- `command-optimistic-pipeline` — One durable run card per invocation, mutated in place while `SaveCardCommand` writes are queued fire-and-forget. Use for LLM/image/import pipelines that need fast UI and queryable progress logs.
- `command-atomic-install` — Transactional realm install with `PlanBuilder` + `planModuleInstall` + `planInstanceInstall` + `ExecuteAtomicOperationsCommand`. The canonical catalog-install pattern.
- `link-command-menu-item` — Expose a Command as a card menu item via `[getMenuItems]`. The card-native way to surface card-scoped actions.
- `automate-run-command-cli` — Invoke a Command from the shell via `npx boxel run-command <spec> --input '{}'`, pairing with a typed run card for queryable history. Batch jobs, cron, CI gates.

For the wider taxonomy (direct call, reactive resource, menu, typed progress, optimistic pipeline, AI processor, multi-turn assistant, CLI script, atomic install) and a single Command class exposed via every mode, see [`boxel/references/command-invocation-modes.md`](../boxel/references/command-invocation-modes.md).

### Organize

- `organize-base-class-taxonomy` — An empty base CardDef as a query-by-type taxonomy. No `kind` field needed.
- `organize-variant-field-dispatcher` — A FieldDef that swaps among 3–5 edit components by `configuration.variant`.
- `organize-atomic-field-factory` — Factory `createOptionSelectField({ options, view })` returning a `class extends StringField`.
- `organize-resource-class-data-loader` — Resource subclass with a **boxed** constructor (`{ ctor, fields }`) to side-step Glimmer's `{{...}}` auto-binding bug.
- `organize-lru-cached-parser` — Generic `LruCache<K,V>` using `Map`-insertion-order eviction.
- `organize-recursive-fielddef` — Self-referential nested structures with `@field replies = containsMany(() => CommentThread)`. The lazy arrow is the required syntax for threaded comments, org charts, file trees, and nested categories.
- `organize-sensitive-stub-pair` — Sensitive full record + safe operational stub kept in sync via a projection Command. Full record owns the link to the stub; app surfaces link to the stub. A `syncIssues` getter surfaces drift in the UI. Use for school/HR records, healthcare charts, any private-vs-public projection.
- `organize-typed-activity-feed` — Base `FeedEntry` CardDef + N specialized subclasses (Academic / Behavioral / Social / …) sharing common chrome. Queries against the base get mixed-type streams; queries against a subclass get filtered streams. Replaces single-Entry-with-giant-`kind`-enum + conditional rendering shapes.

From cardstack/boxel-skills, MIT.

More from cardstack/boxel-skills