brustjs 0.1.16-alpha → 0.1.18-alpha

package/example/pokedex/lib/loaders.ts

@@ -0,0 +1,290 @@
+// Route loaders. Each runs in a Bun worker (full JS), fetches from PokeAPI, and
+// returns a fully render-ready view-model. Templates now do conditionals (S11),
+// `style={{…}}` objects (S1), and dynamic head props (S8); the loader still
+// precomputes formatted strings, booleans for conditionals, and multi-property
+// style strings (no template-literals / arithmetic / helper calls in templates).
+// See ../FRAMEWORK-GAPS.md.
+
+import { z } from 'zod'
+import { type BrustRequest, type NativeVerdict, notFound } from 'brustjs/routes'
+import {
+  ALL_TYPES,
+  artwork,
+  cap,
+  fetchEvolution,
+  fetchList,
+  fetchPokemon,
+  fetchSpecies,
+  fetchTypeRelations,
+  pad,
+  STAT_LABEL,
+  statBucket,
+  TYPE_COLOR,
+} from './pokeapi'
+import { teamStore } from './team-store'
+import type { DetailData, ListData, TypeBadgeVM, TypeChartData } from './types'
+
+/** Loader context shape — `loader: ({ params, path, req }) => data`. */
+interface LoaderCtx {
+  params: Record<string, string>
+  path: string
+  req: BrustRequest
+}
+
+const PAGE = 20
+const NATIONAL_MAX = 1302
+
+// GAP S1: query validation is not symmetric with actions. Actions bind a schema
+// in the descriptor and hand the handler a typed+validated `query`; loaders get
+// `req.search` as a raw Record<string,string> and must validate by hand here.
+const ListQuery = z.object({
+  offset: z.coerce.number().int().min(0).max(NATIONAL_MAX).catch(0),
+})
+
+const fmt = (n: number) => n.toLocaleString('en-US')
+const typeBadge = (t: string): TypeBadgeVM => ({
+  label: cap(t),
+  className: `dex-type dex-type--${t}`,
+})
+
+export async function listLoader({ req }: LoaderCtx): Promise<ListData> {
+  const offset = ListQuery.parse(req?.search ?? {}).offset
+  const { results, total } = await fetchList(offset, PAGE)
+
+  const items = results.map((r) => ({
+    id: r.id,
+    name: r.name,
+    displayName: cap(r.name),
+    num: pad(r.id),
+    artwork: artwork(r.id),
+    detailHref: `/pokemon/${r.name}`,
+  }))
+
+  const lastPage = Math.ceil(total / PAGE)
+  const pageNo = Math.floor(offset / PAGE) + 1
+  const hasPrev = offset > 0
+  const hasNext = offset + PAGE < total
+  const prevOffset = Math.max(0, offset - PAGE)
+
+  return {
+    items,
+    total,
+    totalLabel: fmt(total),
+    offset,
+    offsetLabel: String(offset),
+    showingLabel: `${fmt(offset + 1)}–${fmt(Math.min(offset + PAGE, total))} of ${fmt(total)}`,
+    pageLabel: `${pageNo} / ${lastPage}`,
+    // Real conditionals now exist in native routes (GAPS S11 closed): the
+    // template branches on these booleans with `{flags.hasPrev ? <a/> : <span/>}`
+    // instead of always-rendering a loader-computed hide-class.
+    hasPrev,
+    hasNext,
+    prevHref: hasPrev ? (prevOffset > 0 ? `/?offset=${prevOffset}` : '/') : '#',
+    nextHref: hasNext ? `/?offset=${offset + PAGE}` : '#',
+    teamProps: { teamInitial: teamStore.list() },
+  }
+}
+
+export async function detailLoader({ params }: LoaderCtx): Promise<DetailData | NativeVerdict> {
+  const name = params?.name ?? ''
+  const empty = emptyDetail(name)
+
+  const p = await fetchPokemon(name)
+  // GAP S9 (FIXED): native loaders can now `return notFound(data)` to render the
+  // route's OWN template with HTTP 404. The `notFound: true` flag on `empty`
+  // still drives the template's 404-block branch (S11); the sentinel sets the
+  // HTTP STATUS (404 instead of 200). They are complementary. See GAPS S9.
+  if (!p) return notFound(empty)
+
+  const species = await fetchSpecies(p.id)
+  // GAP (native↔streaming): a native route renders in Rust with NO React tree,
+  // so <Suspense> streaming is impossible. The evolution chain — the slow fetch
+  // the design wanted to stream — is therefore loaded BLOCKING here in the
+  // loader. See GAPS S3.
+  const rawEvo = await fetchEvolution(species.evolutionUrl)
+
+  const primary = p.types[0] ?? 'normal'
+  const tint = TYPE_COLOR[primary] ?? 'var(--primary-500)'
+
+  const stats = p.stats.map((s) => {
+    const pct = Math.min(100, Math.round((s.base / 200) * 100))
+    return {
+      label: STAT_LABEL[s.name] ?? s.name,
+      base: s.base,
+      // Bare percent — the template builds the declaration via the S1 style
+      // object: `style={{ width: st.barWidth }}` → `width:62%`.
+      barWidth: `${pct}%`,
+      barClassName: `dex-statbar__fill dex-statbar__fill--${statBucket(s.base)}`,
+    }
+  })
+
+  const abilities = p.abilities.map((a) => ({
+    displayName: cap(a),
+    initial: a.charAt(0).toUpperCase(),
+    // Bare color value — template does `style={{ background: a.iconColor }}`.
+    iconColor: tint,
+  }))
+
+  const evolution = rawEvo.map((s, i) => ({
+    id: s.id,
+    name: s.name,
+    displayName: cap(s.name),
+    num: pad(s.id),
+    artwork: artwork(s.id),
+    detailHref: `/pokemon/${s.name}`,
+    levelLabel: s.minLevel != null ? `Lv ${s.minLevel}` : '',
+    // Real per-item conditionals now work in native routes (S11): the template
+    // tests these booleans instead of toggling a precomputed `dex-hide` class.
+    isFirst: i === 0,
+    showLevel: i > 0 && s.minLevel != null,
+    cardClassName: s.id === p.id ? 'dex-evo__card dex-evo__card--current' : 'dex-evo__card',
+  }))
+
+  const hasEvolution = evolution.length > 1
+
+  return {
+    notFound: false,
+    pageTitle: `${cap(p.name)} · PokéDex`,
+    name: p.name,
+    id: p.id,
+    displayName: cap(p.name),
+    num: pad(p.id),
+    artwork: p.artwork,
+    genus: species.genus,
+    flavorText: species.flavorText,
+    heightLabel: `${(p.height / 10).toFixed(1)} m`,
+    weightLabel: `${(p.weight / 10).toFixed(1)} kg`,
+    abilityCount: p.abilities.length,
+    heroBg: `linear-gradient(160deg, color-mix(in srgb, ${tint} 22%, var(--surface-raised)), var(--surface-raised) 70%)`,
+    types: p.types.map(typeBadge),
+    stats,
+    statTotal: p.stats.reduce((a, s) => a + s.base, 0),
+    abilities,
+    hasAbilities: abilities.length > 0,
+    evolution,
+    hasEvolution,
+    addProps: {
+      id: p.id,
+      name: p.name,
+      displayName: cap(p.name),
+      num: pad(p.id),
+      types: p.types,
+      artwork: p.artwork,
+    },
+    teamProps: { teamInitial: teamStore.list() },
+  }
+}
+
+function emptyDetail(name: string): DetailData {
+  return {
+    notFound: true,
+    pageTitle: `${cap(name)} · PokéDex`,
+    name,
+    id: 0,
+    displayName: cap(name),
+    num: '',
+    artwork: '',
+    genus: '',
+    flavorText: '',
+    heightLabel: '',
+    weightLabel: '',
+    abilityCount: 0,
+    heroBg: '',
+    types: [],
+    stats: [],
+    statTotal: 0,
+    abilities: [],
+    hasAbilities: false,
+    evolution: [],
+    hasEvolution: false,
+    addProps: { id: 0, name, displayName: cap(name), num: '', types: [], artwork: '' },
+    teamProps: { teamInitial: teamStore.list() },
+  }
+}
+
+const SHORT: Record<string, string> = {
+  normal: 'NOR',
+  fire: 'FIR',
+  water: 'WAT',
+  electric: 'ELE',
+  grass: 'GRA',
+  ice: 'ICE',
+  fighting: 'FIG',
+  poison: 'POI',
+  ground: 'GRO',
+  flying: 'FLY',
+  psychic: 'PSY',
+  bug: 'BUG',
+  rock: 'ROC',
+  ghost: 'GHO',
+  dragon: 'DRA',
+  dark: 'DAR',
+  steel: 'STE',
+  fairy: 'FAI',
+}
+
+export async function typeChartLoader(): Promise<TypeChartData> {
+  // GAP S2: no loader-level batch/parallel helper or request-scoped cache — we
+  // fan out 18 fetches by hand with Promise.all (and there is no dedupe).
+  const relations = await Promise.all(ALL_TYPES.map((t) => fetchTypeRelations(t)))
+
+  // Flatten the 19×19 grid (1 header row/col + 18×18 matrix) into a single
+  // row-major array so the native template renders it with ONE `.map()`.
+  const cells: Array<Omit<TypeChartData['cells'][number], 'id'>> = []
+
+  // Header row: corner + 18 defending-type column heads.
+  cells.push({
+    className: 'dex-tc__corner',
+    content: 'ATK ＼ DEF',
+    title: 'Attacking ＼ Defending',
+  })
+  for (const def of ALL_TYPES) {
+    cells.push({
+      className: `dex-tc__colhead dex-tc__colhead--${def}`,
+      content: SHORT[def] ?? def.slice(0, 3).toUpperCase(),
+      title: cap(def),
+    })
+  }
+
+  // One row per attacking type: row head + 18 effectiveness cells.
+  ALL_TYPES.forEach((atk, i) => {
+    const rel = relations[i]!
+    cells.push({
+      className: `dex-tc__rowhead dex-tc__rowhead--${atk}`,
+      content: SHORT[atk] ?? atk.slice(0, 3).toUpperCase(),
+      title: cap(atk),
+    })
+    for (const def of ALL_TYPES) {
+      const mult = rel[def]
+      if (mult === 2)
+        cells.push({
+          className: 'dex-tc__cell dex-tc__cell--super',
+          content: '2',
+          title: `${cap(atk)} → ${cap(def)}: 2× (super effective)`,
+        })
+      else if (mult === 0.5)
+        cells.push({
+          className: 'dex-tc__cell dex-tc__cell--weak',
+          content: '½',
+          title: `${cap(atk)} → ${cap(def)}: ½× (not very effective)`,
+        })
+      else if (mult === 0)
+        cells.push({
+          className: 'dex-tc__cell dex-tc__cell--none',
+          content: '0',
+          title: `${cap(atk)} → ${cap(def)}: 0× (no effect)`,
+        })
+      else
+        cells.push({
+          className: 'dex-tc__cell',
+          content: '',
+          title: `${cap(atk)} → ${cap(def)}: 1×`,
+        })
+    }
+  })
+
+  return {
+    cells: cells.map((c, i) => ({ id: String(i), ...c })),
+    teamProps: { teamInitial: teamStore.list() },
+  }
+}

package/example/pokedex/lib/pokeapi.ts

@@ -0,0 +1,174 @@
+// PokeAPI fetch wrappers + formatting helpers.
+//
+// These run inside route LOADERS (plain Bun/JS — full language, no native
+// constraint). Their job is to fetch from PokeAPI and return fully render-ready
+// view-models so the native (jinja) page templates only interpolate fields.
+
+export const API = 'https://pokeapi.co/api/v2'
+
+export const idFromUrl = (url: string): number => Number((url.match(/\/pokemon\/(\d+)\//) || [])[1])
+
+/** Official-artwork PNG from the PokeAPI sprites CDN — derived from id so the
+ *  list page needs ONE PokeAPI call per page (no per-Pokémon detail fetch). */
+export const artwork = (id: number): string =>
+  `https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/${id}.png`
+
+export const cap = (s: string): string =>
+  s ? s.charAt(0).toUpperCase() + s.slice(1).replace(/-/g, ' ') : s
+
+export const pad = (n: number): string => `#${String(n).padStart(4, '0')}`
+
+/** Pokémon type → AssetsArt design-token CSS variable (stays inside brand —
+ *  no canonical Pokémon colours). Mirrored by `.dex-type--<name>` rules in
+ *  app.css. */
+export const TYPE_COLOR: Record<string, string> = {
+  normal: 'var(--ink-400)',
+  fire: 'var(--magenta-500)',
+  water: 'var(--blue-500)',
+  grass: 'var(--success-500)',
+  electric: 'var(--warning-500)',
+  ice: 'var(--viz-4)',
+  fighting: 'var(--viz-3)',
+  poison: 'var(--purple-600)',
+  ground: 'var(--viz-7)',
+  flying: 'var(--viz-5)',
+  psychic: 'var(--purple-500)',
+  bug: 'var(--viz-8)',
+  rock: 'var(--ink-500)',
+  ghost: 'var(--purple-700)',
+  dragon: 'var(--viz-2)',
+  dark: 'var(--ink-800)',
+  steel: 'var(--ink-400)',
+  fairy: 'var(--magenta-300)',
+}
+
+export const STAT_LABEL: Record<string, string> = {
+  hp: 'HP',
+  attack: 'Atk',
+  defense: 'Def',
+  'special-attack': 'Sp.Atk',
+  'special-defense': 'Sp.Def',
+  speed: 'Spd',
+}
+
+/** Bucket a base stat into one of three fill modifier classes. */
+export const statBucket = (base: number): string =>
+  base >= 100 ? 'hi' : base >= 60 ? 'mid' : base >= 35 ? 'low' : 'min'
+
+export interface RawPokemon {
+  id: number
+  name: string
+  types: string[]
+  stats: { name: string; base: number }[]
+  height: number
+  weight: number
+  abilities: string[]
+  artwork: string
+}
+
+export interface RawSpecies {
+  flavorText: string
+  genus: string
+  evolutionUrl: string
+}
+
+export interface RawEvolutionStage {
+  id: number
+  name: string
+  minLevel: number | null
+}
+
+export async function fetchList(offset: number, limit: number) {
+  const res = await fetch(`${API}/pokemon?limit=${limit}&offset=${offset}`)
+  if (!res.ok) throw new Error(`PokeAPI list ${res.status}`)
+  const page = (await res.json()) as {
+    count: number
+    results: { name: string; url: string }[]
+  }
+  return {
+    results: page.results.map((r) => ({ id: idFromUrl(r.url), name: r.name })),
+    total: page.count,
+  }
+}
+
+export async function fetchPokemon(name: string): Promise<RawPokemon | null> {
+  const res = await fetch(`${API}/pokemon/${name}`)
+  if (!res.ok) return null
+  const p = (await res.json()) as any
+  return {
+    id: p.id,
+    name: p.name,
+    types: p.types.map((t: any) => t.type.name),
+    stats: p.stats.map((s: any) => ({ name: s.stat.name, base: s.base_stat })),
+    height: p.height,
+    weight: p.weight,
+    abilities: p.abilities.map((a: any) => a.ability.name),
+    artwork: p.sprites?.other?.['official-artwork']?.front_default || artwork(p.id),
+  }
+}
+
+export async function fetchSpecies(id: number): Promise<RawSpecies> {
+  const res = await fetch(`${API}/pokemon-species/${id}`)
+  const s = (await res.json()) as any
+  const flavor = s.flavor_text_entries?.find((e: any) => e.language.name === 'en')?.flavor_text as
+    | string
+    | undefined
+  return {
+    flavorText: (flavor || '').replace(/[\n\f\r]+/g, ' ').trim(),
+    genus: s.genera?.find((g: any) => g.language.name === 'en')?.genus || '',
+    evolutionUrl: s.evolution_chain?.url || '',
+  }
+}
+
+/** Walk the (linear) evolution chain. Branching chains (e.g. Eevee) are
+ *  flattened to the first branch — noted as an open question in the design. */
+export async function fetchEvolution(url: string): Promise<RawEvolutionStage[]> {
+  if (!url) return []
+  const res = await fetch(url)
+  if (!res.ok) return []
+  const data = (await res.json()) as any
+  const stages: RawEvolutionStage[] = []
+  let node = data.chain
+  while (node) {
+    const id = idFromUrl(node.species.url.replace('-species', ''))
+    const det = node.evolution_details?.[0] || {}
+    stages.push({ id, name: node.species.name, minLevel: det.min_level || null })
+    node = node.evolves_to?.[0]
+  }
+  return stages
+}
+
+/** The 18 canonical type names, in chart order. */
+export const ALL_TYPES = [
+  'normal',
+  'fire',
+  'water',
+  'electric',
+  'grass',
+  'ice',
+  'fighting',
+  'poison',
+  'ground',
+  'flying',
+  'psychic',
+  'bug',
+  'rock',
+  'ghost',
+  'dragon',
+  'dark',
+  'steel',
+  'fairy',
+]
+
+/** Fetch one type's damage relations → a map of defendingType → multiplier. */
+export async function fetchTypeRelations(type: string): Promise<Record<string, number>> {
+  const res = await fetch(`${API}/type/${type}`)
+  if (!res.ok) return {}
+  const d = (await res.json()) as any
+  const rel = d.damage_relations
+  const out: Record<string, number> = {}
+  for (const t of rel.double_damage_to || []) out[t.name] = 2
+  for (const t of rel.half_damage_to || []) out[t.name] = 0.5
+  for (const t of rel.no_damage_to || []) out[t.name] = 0
+  return out
+}

package/example/pokedex/lib/team-store.ts

@@ -0,0 +1,28 @@
+// In-process team store — a module-scope Map that lives for the whole server
+// process. It is GLOBAL across every request and every visitor: brust ships no
+// per-session / request-context primitive, so for this dogfood the team is a
+// single shared roster. See ../FRAMEWORK-GAPS.md S6.
+
+import type { TeamMember } from './types'
+
+const team = new Map<number, TeamMember>()
+export const MAX_TEAM = 6
+
+export const teamStore = {
+  list: (): TeamMember[] => [...team.values()].sort((a, b) => a.addedAt - b.addedAt),
+
+  /** Add a member. Returns `false` when the team is full (and the member is
+   *  new); idempotent for a member already on the team. */
+  add: (m: Omit<TeamMember, 'addedAt'>): boolean => {
+    if (team.has(m.id)) return true
+    if (team.size >= MAX_TEAM) return false
+    team.set(m.id, { ...m, addedAt: Date.now() })
+    return true
+  },
+
+  remove: (id: number): void => {
+    team.delete(id)
+  },
+
+  isFull: (): boolean => team.size >= MAX_TEAM,
+}

package/example/pokedex/lib/types.ts

@@ -0,0 +1,137 @@
+// Domain + view-model types for the PokéDex example.
+//
+// NATIVE NOTE: the page components are `native: true` routes compiled to
+// minijinja. They now support conditionals (S11), `style={{…}}` object attrs
+// (S1), and dynamic `<BrustPage>` head props (S8) — all ✅ FIXED. Still
+// precomputed in the loader: formatted strings, helper-derived values, and
+// multi-property style strings (templates have no template-literals / arithmetic
+// / helper calls). See ../FRAMEWORK-GAPS.md.
+
+/** A single list cell — derived from the list endpoint alone (no detail fetch,
+ *  see FRAMEWORK-GAPS.md S2 / N+1 avoidance). */
+export interface CardVM {
+  id: number
+  name: string
+  displayName: string // "Bulbasaur"
+  num: string // "#0001"
+  artwork: string // CDN URL derived from id
+  detailHref: string // "/pokemon/bulbasaur"
+}
+
+export interface ListData {
+  items: CardVM[]
+  total: number
+  totalLabel: string // "1,302"
+  offset: number
+  showingLabel: string // "1–20 of 1,302"
+  pageLabel: string // "1 / 66"
+  // Native routes now support conditionals (GAPS S11 closed): the template
+  // branches with `{flags.hasPrev ? <a/> : <span/>}` on these booleans.
+  hasPrev: boolean
+  hasNext: boolean
+  prevHref: string
+  nextHref: string
+  offsetLabel: string // raw offset for the loader-echo line
+  teamProps: { teamInitial: TeamMember[] }
+}
+
+export interface TypeBadgeVM {
+  label: string // "Grass"
+  className: string // "dex-type dex-type--grass"
+}
+
+export interface StatVM {
+  label: string // "HP" / "Atk" / …
+  base: number
+  barWidth: string // "62%" — fed into `style={{ width: barWidth }}` (S1)
+  barClassName: string // "dex-statbar__fill dex-statbar__fill--mid"
+}
+
+export interface AbilityVM {
+  displayName: string // "Overgrow"
+  initial: string // "O"
+  iconColor: string // type tint — fed into `style={{ background: iconColor }}` (S1)
+}
+
+export interface EvolutionStageVM {
+  id: number
+  name: string
+  displayName: string
+  num: string
+  artwork: string
+  detailHref: string
+  levelLabel: string // "Lv 16"
+  // Native routes now support per-item conditionals (GAPS S11 closed): the
+  // template tests these booleans (`{!s.isFirst && <Arrow/>}`) instead of
+  // toggling a precomputed `dex-hide` class.
+  isFirst: boolean // true on the first stage (no leading arrow)
+  showLevel: boolean // true when this stage has a min level to show
+  cardClassName: string // adds the "current" highlight when this is the open Pokémon
+}
+
+/** The full view-model handed to DetailPage. Every field is render-ready. */
+export interface DetailData {
+  notFound: boolean
+  // Native routes now branch with `{notFound ? <NotFound/> : <Content/>}` (S11),
+  // so the content and 404 block are mutually exclusive at render time rather
+  // than both emitted with one hidden via a precomputed class.
+  pageTitle: string // dynamic <title> via `<BrustPage title={d.pageTitle}>` (S8)
+  name: string
+  // present only when notFound === false:
+  id: number
+  displayName: string
+  num: string
+  artwork: string
+  genus: string
+  flavorText: string
+  heightLabel: string // "0.7 m"
+  weightLabel: string // "6.9 kg"
+  abilityCount: number
+  heroBg: string // gradient value for `style={{ background: heroBg }}` — type-tinted
+  types: TypeBadgeVM[]
+  stats: StatVM[]
+  statTotal: number
+  abilities: AbilityVM[]
+  hasAbilities: boolean
+  evolution: EvolutionStageVM[]
+  hasEvolution: boolean
+  // island props (a single path each — native island props can't be object literals):
+  addProps: AddToTeamProps
+  teamProps: { teamInitial: TeamMember[] }
+}
+
+/** Props for the AddToTeamButton island (raw types kept for the action body). */
+export interface AddToTeamProps {
+  id: number
+  name: string
+  displayName: string
+  num: string
+  types: string[]
+  artwork: string
+}
+
+/** One cell of the type chart, FLATTENED into a single row-major array so the
+ *  native template renders it with ONE `.map()` into a CSS grid — nested maps
+ *  aren't proven on the native path, so we avoid them. See FRAMEWORK-GAPS.md S10. */
+export interface TypeChartCellVM {
+  id: string // stable key (row/col coordinate)
+  className: string // "dex-tc__cell dex-tc__cell--super"
+  content: string // "2", "½", "0", a type short-code, or ""
+  title: string // tooltip
+}
+
+export interface TypeChartData {
+  cells: TypeChartCellVM[] // (18+1) × (18+1) row-major, including headers
+  teamProps: { teamInitial: TeamMember[] }
+}
+
+/** In-process team store member. */
+export interface TeamMember {
+  id: number
+  name: string
+  displayName: string
+  types: string[]
+  artwork: string
+  num: string
+  addedAt: number
+}