Cs 9803 migrate field configuration showcases #3811

lucaslyl · 2026-01-08T08:49:57Z

Migrate field specs from field-showcase to individual subclass specs

This is the first pass to migrate fields from field-showcase to each subclass spec.

This change:

Creates spec for subclass override with isolated and edit templates
Adds reusable FieldSpecIsolatedTemplate and FieldSpecEditTemplate components for subclass specs
Removes field-showcase dependency
Updates all field spec subclasses to use the new shared templates

FieldSpecIsolatedTemplate / FieldSpecEditTemplate include the Field Configuration Playground (dynamic fields) and hide the example section, which differs from the Base Spec template.te and FieldSpecEditTemplate include the Field Configuration Playground (dynamic fields) and hide the example section, which differs from the Base Spec template.

Demo:

Screen.Recording.2026-01-08.at.6.21.03.PM.mov

Follow-up task:

https://linear.app/cardstack/issue/CS-9974/base-spec-isolatededit-and-subclass-spec-isolatededit-templates-have
In the catalog, we override the Subclass Spec isolated/edit template to display the Field Configuration Playground (dynamic fields / hide the example section). However, most of the remaining code is the same as
the Base Spec template.

We discussed whether we should move the shared isolatedTemplate and editTemplate components into the Base Spec (so both base spec and subclass spec can reuse it), or introduce a shared implementation that both Base and Subclass specs can reference. ** Currently all subclass spec is located under catalog-realms **

…Field adn override the base spec edit/isolated template (remove example section too )

github-actions · 2026-01-08T08:57:32Z

Preview deployments

github-actions · 2026-01-08T09:08:52Z

Host Test Results

1 files ± 0 1 suites ±0 1h 35m 44s ⏱️ + 5m 39s
1 856 tests +216 1 839 ✅ +216 15 💤 ±0 0 ❌ - 1 2 🔥 +1
1 871 runs +217 1 852 ✅ +216 15 💤 ±0 2 ❌ ±0 2 🔥 +1

For more details on these errors, see this check.

Results for commit 3ff3f13. ± Comparison against base commit b2f9b85.

This pull request removes 1 and adds 217 tests. Note that renamed tests count towards both.

Chrome ‑ Global error: Uncaught TypeError: Failed to fetch at http://localhost:7357/assets/chunk.87676936a9f50c566053.js, line 153748  While executing test: Integration | card-copy: copy button does not appear when right and left stacks are both index cards but there are selections on both sides

Chrome ‑ Integration | Command | create-specs: subclassed spec with custom edit template hides Examples section
Chrome ‑ Integration | Command | create-specs: subclassed spec with custom edit template shows Field Configuration Playground section
Chrome ‑ Integration | Store: added instance that was previously not saved will begin to auto save after being added
Chrome ‑ Integration | Store: an instance can be restored after a loader reset
Chrome ‑ Integration | Store: an instance can debounce auto saves
Chrome ‑ Integration | Store: an instance can live update thru an error state
Chrome ‑ Integration | Store: an instance live updates from indexing events for a code update
Chrome ‑ Integration | Store: an instance live updates from indexing events for an instance update
Chrome ‑ Integration | Store: an instance that started out with a local ID can be restored after a loader reset
Chrome ‑ Integration | Store: an instance will NOT auto save when its data changes, if the user does not have write permissions
…

♻️ This comment has been updated with latest results.

lucaslyl · 2026-01-08T10:41:19Z

packages/catalog-realm/field-spec/audio-field-spec.gts

+
+  static isolated =
+    FieldSpecIsolatedTemplate as unknown as typeof Spec.isolated;
+  static edit = FieldSpecEditTemplate as unknown as typeof Spec.edit;


TypeScript can't verify the compatibility directly. I use this double type assertion (as unknown as typeof Spec.isolated) to tell TypeScript the template is compatible with the expected type

packages/catalog-realm/components/field-renderer.gts

tintinthong · 2026-01-09T02:32:01Z

packages/catalog-realm/field-spec/AudioFieldSpec/aad14b4f-2b08-468f-ab34-18d9890c39c3.json

+    "attributes": {
+      "ref": {
+        "name": "AudioFieldSpec",
+        "module": "http://localhost:4201/catalog/field-spec/audio-field-spec"


why are the refs absolulte? How is this gonna work in live environment

Yes, I think this is a bug in the existing create-spec command. I searched through the spec instances created recently, and they all point to an absolute path. I’ll work on changing this behavior so it uses relative paths instead.

tintinthong · 2026-01-09T02:34:47Z

packages/host/tests/integration/commands/create-spec-test.gts

      'readMe content sourced from proxy mock',
    );
  });
+


does this test work? I thought we had to copy over files for host test that depend on catalog now

ya ,it work but sometimes it flaky in the host test, i wil investigate this

tintinthong · 2026-01-09T02:36:46Z

packages/host/app/commands/create-specs.ts

    const title = this.getSpecTitle(declaration, codeRef.name);
    const specType = new SpecTypeGuesser(declaration).type;

+    const specClassToUse = await getSpecClassFromDeclaration(


lets just call this specKlass as before

I will to rename this to ResolvedSpecKlass because this function also passes SpecKlass as an argument.

lucaslyl · 2026-01-09T10:24:03Z

packages/runtime-common/file-serializer.ts

      relativeTo,
-      codeRefOpts,
+      codeRefOpts: metaCodeRefOpts,
      customFieldDefinitions,


@tintinthong

Here is my research.

When creating a Spec, the ref.module field (a CodeRef in attributes) was stored as an absolute URL (e.g., "http://localhost:4200/catalog-realm/blog-app") instead of a relative URL (e.g., "../blog-app/blog-app").

Root Cause:
In file-serializer.ts, processAttributes used codeRefOpts, which lacks:

allowRelative: true

maybeRelativeURL function

Without these, codeRefAdjustments couldn't convert absolute URLs to relative ones during serialization.

Solution:

Changed processAttributes to use metaCodeRefOpts instead of codeRefOpts. metaCodeRefOpts includes:
allowRelative: true — enables relative URL conversion
maybeRelativeURL — converts absolute URLs to relative when realmURL is available

Here is the demo after i made this changes:

Screen.Recording.2026-01-09.at.5.59.09.PM.mov

…e URLs

… top

habdelra · 2026-01-09T14:24:36Z

packages/host/app/commands/create-specs.ts

+ */
+async function getSpecClassFromDeclaration(
+  codeRef: ResolvedCodeRef,
+  fallbackSpecClass: typeof BaseDef,


wouldnt this be a typeof CardDef--Specs are Cards not fields

Agreed with it, the issue has been addressed

Copilot

Pull request overview

This PR migrates field configuration showcases from a single centralized field-showcase component to individual field spec subclasses with reusable templates. The changes introduce two new template components (FieldSpecIsolatedTemplate and FieldSpecEditTemplate) that provide the Field Configuration Playground functionality while removing the dependency on the large field-showcase file.

Key Changes

Created reusable FieldSpecIsolatedTemplate and FieldSpecEditTemplate components for field spec subclasses
Implemented 20+ individual field spec files (AudioFieldSpec, ColorFieldSpec, DateFieldSpec, etc.) with proper configurations
Enhanced create-specs command to automatically use spec subclasses when available
Removed the monolithic field-showcase.gts file (~4000 lines) and its instance data

Reviewed changes

Copilot reviewed 70 out of 71 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
`field-spec/components/field-spec-isolated-template.gts`	New reusable isolated template component for field specs with Field Configuration Playground
`field-spec/components/field-spec-edit-template.gts`	New reusable edit template component for field specs with Generate README button
`utils/is-own-field.ts`	Utility to filter inherited fields from own fields in field specs
`field-spec/*-field-spec.gts`	20+ new field spec files with field configurations and custom templates
`commands/create-specs.ts`	Enhanced to automatically detect and use spec subclasses
`tests/integration/commands/create-spec-test.gts`	Added tests for custom templates in subclassed specs
`runtime-common/file-serializer.ts`	Variable rename for clarity
`fields-preview/field-showcase.gts`	Deleted 4000-line monolithic showcase file
Various JSON files	New spec instances and supporting image data

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

habdelra · 2026-01-09T14:28:22Z

packages/catalog-realm/utils/is-own-field.ts

+import type { BaseDef } from 'https://cardstack.com/base/card-api';
+
+// When checking ColorFieldSpec:
+// ✅ Returns: 'standard', 'wheel', 'sliderRgb', etc. (directly on ColorFieldSpec)
+// ❌ Does NOT return: 'readMe', 'ref', 'title' (from Spec.prototype - inherited)
+// ❌ Does NOT return: 'id' (from CardDef.prototype - inherited)
+export function isOwnField(card: typeof BaseDef, fieldName: string): boolean {
+  return Object.keys(Object.getOwnPropertyDescriptors(card.prototype)).includes(
+    fieldName,
+  );
+}


This is a dupe of the schema-editor.ts's isOwnFields() function. instead of duplicating, please create function in runtime-common that can be shared by these two

Great catch. Thanks for the review and suggestion. I’ve created a shared isOwnField utility in runtime-common

lucaslyl added 4 commits January 8, 2026 16:26

Support subclass spec template override

d1fadfb

Create all subclass spec edit and isolated components to render isOwn…

35acdb9

…Field adn override the base spec edit/isolated template (remove example section too )

update the subclass spec instances

249aa96

Merge branch 'main' into CS-9803-migrate-field-configuration-showcases

d2ace51

lucaslyl added 2 commits January 8, 2026 18:04

fix lint

21047ea

remove field-showcase

8fa1861

lucaslyl self-assigned this Jan 8, 2026

lucaslyl requested a review from a team January 8, 2026 10:33

lucaslyl commented Jan 8, 2026

View reviewed changes

lucaslyl added 2 commits January 8, 2026 20:16

Merge branch 'main' into CS-9803-migrate-field-configuration-showcases

6673da0

add test

810464a

lucaslyl requested a review from a team January 8, 2026 13:19

lucaslyl marked this pull request as ready for review January 8, 2026 13:19

fix lint

4ed1103

tintinthong reviewed Jan 9, 2026

View reviewed changes

packages/catalog-realm/components/field-renderer.gts Show resolved Hide resolved

tintinthong reviewed Jan 9, 2026

View reviewed changes

lucaslyl commented Jan 9, 2026

View reviewed changes

Fix: Use metaCodeRefOpts for attributes to convert CodeRef to relativ…

292e6c3

…e URLs

lucaslyl force-pushed the CS-9803-migrate-field-configuration-showcases branch from eb05214 to 292e6c3 Compare January 9, 2026 11:07

lucaslyl added 2 commits January 9, 2026 19:55

simplify the type of fieldrenderer

fe52816

refactored the test file to extract source code into constants at the…

429ee95

… top

lucaslyl requested a review from tintinthong January 9, 2026 12:04

habdelra requested a review from Copilot January 9, 2026 14:20

Copilot started reviewing on behalf of habdelra January 9, 2026 14:21 View session

habdelra reviewed Jan 9, 2026

View reviewed changes

Copilot AI reviewed Jan 9, 2026

View reviewed changes

habdelra reviewed Jan 9, 2026

View reviewed changes

lucaslyl added 2 commits January 9, 2026 23:32

improve type on getSpecClassFromDeclaration

f45b4a8

create sharable isOwnField function at runtime-common

3ff3f13

lucaslyl requested a review from habdelra January 9, 2026 16:12

Cs 9803 migrate field configuration showcases #3811

Are you sure you want to change the base?

Cs 9803 migrate field configuration showcases #3811

Uh oh!

Conversation

lucaslyl commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

This change:

Demo:

Follow-up task:

Uh oh!

github-actions bot commented Jan 8, 2026

Preview deployments

Uh oh!

github-actions bot commented Jan 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Host Test Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tintinthong Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucaslyl Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucaslyl Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lucaslyl commented Jan 8, 2026 •

edited

Loading

github-actions bot commented Jan 8, 2026 •

edited

Loading

tintinthong Jan 9, 2026 •

edited

Loading

lucaslyl Jan 9, 2026 •

edited

Loading

lucaslyl Jan 9, 2026 •

edited

Loading