@homepages/template-kit 0.2.0 → 0.4.0

package/docs/vocabulary.md

@@ -0,0 +1,98 @@
+---
+purpose: The closed authoring vocabulary — slot types, direct() sources, derived() transforms, with selection semantics.
+status: living
+related: [schema-system.md]
+updated: 2026-07-15
+---
+# The closed authoring vocabulary
+
+Three closed sets. A slot's `type` picks its runtime value shape; a slot's
+`source` (`direct()` or `derived()`) picks which fact or computation fills it.
+This page is a selection reference — *which one to pick* — not a restatement
+of their field shapes.
+
+## Slot types
+
+| type | runtime value shape | pick it when |
+|---|---|---|
+| `text` | `string` (`string \| null` if optional) | one editable line/paragraph (`size` short\|medium\|long) |
+| `number` | `number` (`number \| null` if optional) | a numeric fact with formatting |
+| `select` | `string` (`string \| null` if optional) | a closed set of choices the user picks from |
+| `image` | `ImageValue` (`ImageValue \| null` if optional) | one framed photo (add `crop`/`frame`) |
+| `image_collection` | `ImageCollectionValue` | a gallery of framed photos |
+| `list` | `string[]` for a `text` element, `unknown[]` otherwise | a flat list of scalar items |
+| `poi_list` | `PoiRow[]` | neighborhood points of interest |
+| `url` | `string` (`string \| null` if optional) | a link the user edits in a URL field |
+| `object_list` | `Record<string, unknown>[]` | repeating, independently-editable multi-field items |
+
+The full per-type field shapes live in your editor's autocomplete and
+[schema-system.md](schema-system.md) — this page is only *which to pick*.
+
+## `direct()` sources
+
+The property facts a slot binds verbatim. A bad name is a compile error at
+the `direct(...)` call site.
+
+**Property facts** (resolve once per property):
+- `address` — the full formatted address
+- `listing_intent` — for-sale vs. for-rent state
+- `status` — the listing status, free text as shown on the listing (e.g. "For Sale")
+- `property_type` — the property type (`single_family` \| `condo_townhome` \| `multi_family` \| `investment`)
+- `year_built` — the year the property was built
+- `lot_size` — the lot size, pre-formatted text
+
+**Per-unit facts** (resolve against the current/single unit row):
+- `unit_label` — the unit's display label (e.g. "Unit 3B")
+- `beds` — bedroom count for this unit
+- `baths` — bathroom count for this unit
+- `sqft` — square footage for this unit
+- `price` — this unit's price, pre-formatted text
+- `notes` — free-text notes on this unit
+
+**List sources** (bind the whole array verbatim — pick these for `object_list`
+slots that repeat over every row):
+- `units` — every unit row on the property
+- `contacts` — every contact attached to the section
+
+**Per-contact fields** (resolve against the attached contact):
+- `name` — the contact's display name
+- `title` — the contact's job title/role
+- `bio` — the contact's bio copy
+- `email` — the contact's email address
+- `phone` — the contact's phone number
+- `website` — the contact's website URL
+- `instagram` — the contact's Instagram handle/URL
+- `linkedin` — the contact's LinkedIn handle/URL
+- `x` — the contact's X (Twitter) handle/URL
+- `facebook` — the contact's Facebook handle/URL
+
+**Contact images** (bind only to `image` slots):
+- `headshot` — the contact's headshot photo
+- `logo_dark` — the contact's logo, dark-background variant
+- `logo_light` — the contact's logo, light-background variant
+
+## `derived()` transforms
+
+Computed values, grouped by family. A bad name is a compile error at the
+`derived(...)` call site.
+
+| transform | what it computes |
+|---|---|
+| `units.bedsPrimary` | beds of the primary (lowest-position) unit |
+| `units.bathsPrimary` | baths of the primary unit |
+| `units.sqftPrimary` | sqft of the primary unit |
+| `units.pricePrimary` | price of the primary unit, pre-formatted text |
+| `units.bedsRange` | formatted beds range across all units (e.g. "2–4"), collapsing to one value when uniform |
+| `units.priceStart` | the lowest numeric unit price; falls back to the first non-numeric price (e.g. "Sold") when none is numeric |
+| `units.bedsMin` | the minimum beds across all units, formatted |
+| `units.bedsMax` | the maximum beds across all units, formatted |
+| `units.bathsMin` | the minimum baths across all units, formatted |
+| `units.bathsMax` | the maximum baths across all units, formatted |
+| `units.sqftMax` | the maximum sqft across all units, formatted |
+| `address.line1` | the property address's street line |
+| `address.line2` | the property address's city/state/zip line |
+| `contact_address.line1` | a contact's address street line |
+| `contact_address.line2` | a contact's address city/state/zip line |
+| `clock.currentYear` | the current year (e.g. for a copyright line) |
+| `coordinate.lat` | latitude, split from the property's geocode |
+| `coordinate.lng` | longitude, split from the property's geocode |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homepages/template-kit",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Authoring kit for HomePages marketing-section templates: schema system, contract primitives, theme tokens, and the template-kit CLI.",
   "license": "UNLICENSED",
   "type": "module",
@@ -41,6 +41,10 @@
       "types": "./dist/browser.d.ts",
       "default": "./dist/browser.js"
     },
+    "./ssr": {
+      "types": "./dist/ssr.d.ts",
+      "default": "./dist/ssr.js"
+    },
     "./eslint": {
       "types": "./dist/eslint.d.ts",
       "default": "./dist/eslint.js"
@@ -55,9 +59,10 @@
   ],
   "scripts": {
     "prepack": "npm run build",
-    "build": "tsdown",
+    "build": "tsdown && node scripts/build-dev-client.mjs && node scripts/build-cli-assets.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
+    "pretest": "node test/link-fixture-workspace.mjs",
     "test": "node --import tsx --test 'src/**/*.test.ts' 'src/**/*.test.tsx'",
     "lint:pkg": "publint --strict && attw --pack . --profile esm-only --exclude-entrypoints styles.css base.css",
     "verify:consumer": "node scripts/verify-consumer.mjs",
@@ -67,24 +72,22 @@
     "release": "changeset publish"
   },
   "peerDependencies": {
-    "eslint": "^9.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
-  "peerDependenciesMeta": {
-    "eslint": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.39.4",
+    "@playwright/test": "^1.60.0",
     "@tailwindcss/cli": "^4.3.0",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^20.17.10",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "@typescript-eslint/parser": "^8.60.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "chokidar": "^4.0.1",
     "esbuild": "^0.28.1",
     "eslint": "^9.39.4",
     "jsdom": "^26.1.0",
@@ -95,10 +98,10 @@
     "tsdown": "0.22.7",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "typescript-eslint": "^8.60.1"
+    "typescript-eslint": "^8.60.1",
+    "vite": "^6.0.5"
   },
   "dependencies": {
-    "@typescript-eslint/parser": "^8.60.1",
-    "zod": "^3.23.8"
+    "zod": "^4.4.3"
   }
 }

package/tsconfig.json

@@ -3,5 +3,5 @@
   "compilerOptions": {
     "noEmit": true
   },
-  "exclude": ["node_modules", "dist", ".tmp-consumer"]
+  "exclude": ["node_modules", "dist", ".tmp-consumer", "test/fixtures", "create-homepages-workspace"]
 }