@owlmeans/create-app 0.1.18-rc.3 → 0.1.18-rc.30

package/template/sources/web/src/context.bare.ts

@@ -0,0 +1,13 @@
+import { makeContext as makeBasicContext, useContext as useBasicContext } from '@owlmeans/web-panel'
+import type { Config, Context } from './types.js'
+
+export const useContext = (): Context => useBasicContext<Config, Context>()
+
+/**
+ * The framework's client store lives ON the context, so a screen, a guard and a service all
+ * reach the same records — which is what separates it from a store held beside the app in a
+ * module of its own. `appendStateResource<C, T>(context, ALIAS)` from '@owlmeans/state'
+ * (already a dependency) registers one; screens then address it by that alias, never by path.
+ */
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =>
+  makeBasicContext<C, T>(cfg)

package/template/sources/web/src/context.ts

@@ -1,7 +1,19 @@
 import { makeContext as makeBasicContext, useContext as useBasicContext } from '@owlmeans/web-panel'
+import { appendStateResource } from '@owlmeans/state'
 import type { Config, Context } from './types.js'
 
+/** The alias the session items are stored under. Screens address the store by it, never by path. */
+export const SESSION_STATE = 'session-items'
+
 export const useContext = (): Context => useBasicContext<Config, Context>()
 
-export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T =>
-  makeBasicContext<C, T>(cfg)
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeBasicContext<C, T>(cfg)
+
+  // The framework's client store. A state resource lives ON the context, so a screen, a guard and
+  // a service all reach the same records — which is what separates it from a store held beside
+  // the app in a module of its own.
+  appendStateResource<C, T>(context, SESSION_STATE)
+
+  return context
+}

package/template/sources/web/src/entrypoints.bare.ts

@@ -0,0 +1,13 @@
+import { bindAll, bindScreen, entrypoints as baseEntrypoints, handler } from '@owlmeans/web-panel'
+import { appProtocols } from '__APP_SLUG__-common'
+import { MainLayout } from './layout/main.js'
+import { HomeScreen } from './screens/home.js'
+
+/** Local browser bindings for shared API and screen protocols. */
+export const appBindings = [
+  ...baseEntrypoints,
+  ...bindAll(appProtocols.api),
+  // BASE renders the shared layout; HOME is its default child.
+  bindScreen(appProtocols.web.base, handler(MainLayout)),
+  bindScreen(appProtocols.web.home, handler(HomeScreen)),
+]

package/template/sources/web/src/entrypoints.ts

@@ -0,0 +1,16 @@
+import { bindAll, bindScreen, entrypoints as baseEntrypoints, handler } from '@owlmeans/web-panel'
+import { appProtocols } from '__APP_SLUG__-common'
+import { MainLayout } from './layout/main.js'
+import { AboutScreen } from './screens/about.js'
+import { HomeScreen } from './screens/home.js'
+import { SessionScreen } from './screens/session.js'
+
+/** Local browser bindings for shared API and screen protocols. */
+export const appBindings = [
+  ...baseEntrypoints,
+  ...bindAll(appProtocols.api),
+  bindScreen(appProtocols.web.base, handler(MainLayout)),
+  bindScreen(appProtocols.web.home, handler(HomeScreen)),
+  bindScreen(appProtocols.web.session, handler(SessionScreen)),
+  bindScreen(appProtocols.web.about, handler(AboutScreen)),
+]

package/template/sources/web/src/index.css

@@ -1,5 +1,12 @@
 @import "tailwindcss";
 
+/*
+ * Tailwind scans this app's sources for class names, and node_modules is excluded from that
+ * scan by default — so the classes that exist ONLY inside @owlmeans/web-panel components
+ * (the navigation shell, the footer) would never reach the stylesheet. This line adds them.
+ */
+@source "../../../node_modules/@owlmeans/web-panel/src";
+
 /*
  * shadcn / Tailwind v4 design tokens (new-york, neutral). The app owns these — they
  * replace what @owlmeans/owl-theme would otherwise provide. The shadcn primitives in

package/template/sources/web/src/index.tsx

@@ -2,12 +2,12 @@ import './index.css'
 import { APP_API, APP_WEB } from '__APP_SLUG__-common'
 import config from './config.js'
 import { makeContext } from './context.js'
-import { appModules } from './modules.js'
+import { appBindings } from './entrypoints.js'
 import { render } from './render.js'
 import type { Config, Context } from './types.js'
 
 const context = makeContext<Config, Context>(config)
-context.registerEntrypoints(appModules)
+context.registerEntrypoints(appBindings)
 
 context.serviceRoute(APP_WEB, true)
 context.serviceRoute(APP_API, true)

package/template/sources/web/src/layout/main.tsx

@@ -1,21 +1,18 @@
 import type { FC, PropsWithChildren } from 'react'
-import { HOME, useNavigate } from '@owlmeans/web-panel'
-import { MainNavigation } from '@/components/nav/main'
+import { NavLayout } from '@owlmeans/web-panel'
+import { footerLinks, navConfig } from '@/nav'
 
-export const MainLayout: FC<PropsWithChildren> = ({ children }) => {
-  const nav = useNavigate()
-
-  return (
-    <div className="min-h-screen bg-background text-foreground">
-      <header className="border-b">
-        <div className="mx-auto flex h-16 max-w-4xl items-center justify-between px-4">
-          <a onClick={nav.press(HOME)} className="cursor-pointer text-lg font-semibold">
-            __APP_NAME__
-          </a>
-          <MainNavigation />
-        </div>
-      </header>
-      <main className="mx-auto max-w-4xl px-4 py-8">{children}</main>
-    </div>
-  )
-}
+/**
+ * The application shell. `NavLayout` renders the header with the section menu, the side menu
+ * of the active section (hidden when that section has a single screen), the content, and the
+ * footer — the screen arrives as `children`.
+ *
+ * The page width comes from the shell, which applies it to the header, the content and the
+ * footer alike; set `containerClassName` to change it for all three at once, never a width on
+ * the content alone.
+ */
+export const MainLayout: FC<PropsWithChildren> = ({ children }) => (
+  <NavLayout nav={navConfig} title="__APP_NAME__" footer={footerLinks}>
+    {children}
+  </NavLayout>
+)

package/template/sources/web/src/nav.bare.ts

@@ -0,0 +1,21 @@
+import { HOME } from '@owlmeans/web-panel'
+import type { PanelNavConfig, PanelNavLink } from '@owlmeans/web-panel'
+
+/**
+ * The application's navigation, as data.
+ *
+ * Sections are the top menu; their items are the side menu of whichever section is active.
+ * A section holding ONE item renders no side menu at all — which is why the single-screen
+ * shell below shows none. Labels here are literal; drop them to fall back on the panel i18n
+ * keys (`nav.<section>` / `modules.<alias>`) instead.
+ */
+export const navConfig: PanelNavConfig = {
+  sections: [
+    { name: 'home', label: 'Home', items: [{ alias: HOME, label: 'Overview' }] },
+  ],
+}
+
+export const footerLinks: PanelNavLink[] = [
+  { alias: HOME, label: '__APP_NAME__' },
+  { href: 'https://owlmeans.com', label: 'OwlMeans', open: true },
+]

package/template/sources/web/src/nav.ts

@@ -0,0 +1,28 @@
+import { HOME } from '@owlmeans/web-panel'
+import type { PanelNavConfig, PanelNavLink } from '@owlmeans/web-panel'
+import { web } from '__APP_SLUG__-common'
+
+/**
+ * The application's navigation, as data.
+ *
+ * Sections are the top menu; their items are the side menu of whichever section is active.
+ * A section holding ONE item renders no side menu at all — `home` below shows that, `demo`
+ * shows the two-level case. Labels here are literal; drop them to fall back on the panel
+ * i18n keys (`nav.<section>` / `modules.<alias>`) instead.
+ */
+export const navConfig: PanelNavConfig = {
+  sections: [
+    { name: 'home', label: 'Home', items: [{ alias: HOME, label: 'Overview' }] },
+    {
+      name: 'demo', label: 'Demo', items: [
+        { alias: web.session.alias, label: 'Session' },
+        { alias: web.about.alias, label: 'About' },
+      ]
+    },
+  ],
+}
+
+export const footerLinks: PanelNavLink[] = [
+  { alias: HOME, label: '__APP_NAME__' },
+  { href: 'https://owlmeans.com', label: 'OwlMeans', open: true },
+]

package/template/sources/web/src/screens/about.tsx

@@ -0,0 +1,19 @@
+import type { FC } from 'react'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+
+export const AboutScreen: FC = () => (
+  <Card>
+    <CardHeader>
+      <CardTitle>About __APP_NAME__</CardTitle>
+      <CardDescription>
+        The second screen of the Demo section — which is why that section shows a side menu
+        and the single-screen Home section does not.
+      </CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p className="text-sm text-muted-foreground">
+        Built with OwlMeans Common. Navigation lives in <code>src/nav.ts</code>.
+      </p>
+    </CardContent>
+  </Card>
+)

package/template/sources/web/src/screens/home.bare.tsx

@@ -0,0 +1,17 @@
+import type { FC } from 'react'
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card'
+
+export const HomeScreen: FC = () => (
+  <Card>
+    <CardHeader>
+      <CardTitle>__APP_NAME__</CardTitle>
+      <CardDescription>__APP_DESCRIPTION__</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p className="text-sm text-muted-foreground">
+        Screens live in <code>src/screens</code>, the menu that reaches them in
+        {' '}<code>src/nav.ts</code>, and the routes they hang off in <code>src/entrypoints.ts</code>.
+      </p>
+    </CardContent>
+  </Card>
+)

package/template/sources/web/src/screens/session.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useState, type FC } from 'react'
-import type { ClientEntrypoint } from '@owlmeans/client-entrypoint'
+import { useStoreList } from '@owlmeans/client'
 import { session, type SessionItem } from '__APP_SLUG__-common'
-import { useContext } from '../context.js'
+import { SESSION_STATE, useContext } from '../context.js'
 import { Button } from '@/components/ui/button'
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
 import { Input } from '@/components/ui/input'
@@ -20,15 +20,27 @@ const sessionId = (): string => {
 export const SessionScreen: FC = () => {
   const ctx = useContext()
   const sid = sessionId()
-  const [items, setItems] = useState<SessionItem[]>([])
   const [text, setText] = useState('')
   const [busy, setBusy] = useState(false)
 
+  const store = ctx.getStateResource<SessionItem>(SESSION_STATE)
+
+  /**
+   * The list is a live subscription to the state resource, not a piece of component state.
+   * Anything that writes a record — this screen or another one — re-renders it, so adding and
+   * removing never re-fetch to stay in step. `{}` matches every record; a real filter goes here.
+   */
+  const items = useStoreList<SessionItem>({ query: {}, resource: SESSION_STATE })
+
+  // The server is the source of truth; the store is what the screen reads. Fetch once, install
+  // what came back, and let the subscription render it. `replace` rather than a save per item:
+  // the endpoint answers with the session's whole set, so an item removed on another tab has to
+  // leave the store too, and one write wakes the subscribers once instead of once per record.
   const load = async () => {
-    const [data] = await ctx
-      .entrypoint<ClientEntrypoint<SessionItem[]>>(session.list)
+    const data = await ctx
+      .entrypoint(session.list)
       .call({ params: { sid } })
-    setItems(data ?? [])
+    await store.replace(data ?? [])
   }
 
   useEffect(() => { void load() }, [])
@@ -37,11 +49,13 @@ export const SessionScreen: FC = () => {
     if (text.trim() === '') return
     setBusy(true)
     try {
-      await ctx
-        .entrypoint<ClientEntrypoint<SessionItem>>(session.add)
+      const item = await ctx
+        .entrypoint(session.add)
         .call({ params: { sid }, body: { text } })
       setText('')
-      await load()
+      if (item != null) {
+        await store.save(item)
+      }
     } finally {
       setBusy(false)
     }
@@ -49,9 +63,9 @@ export const SessionScreen: FC = () => {
 
   const remove = async (id: string) => {
     await ctx
-      .entrypoint<ClientEntrypoint<{ removed: boolean }>>(session.remove)
+      .entrypoint(session.remove)
       .call({ params: { sid, id } })
-    await load()
+    await store.delete(id)
   }
 
   return (
@@ -75,11 +89,11 @@ export const SessionScreen: FC = () => {
         <ul className="flex flex-col gap-2">
           {items.map(item => (
             <li
-              key={item.id}
+              key={item.record.id}
               className="flex items-center justify-between rounded-md border px-3 py-2"
             >
-              <span>{item.text}</span>
-              <Button variant="ghost" size="sm" onClick={() => void remove(item.id)}>
+              <span>{item.record.text}</span>
+              <Button variant="ghost" size="sm" onClick={() => void remove(item.record.id)}>
                 Remove
               </Button>
             </li>

package/template/sources/web/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/template/sources/api/src/modules.ts

@@ -1,11 +0,0 @@
-import { elevate, modules } from '@owlmeans/server-app'
-import { session, sessionModules } from '__APP_SLUG__-common'
-import * as handlers from './app/session/index.js'
-
-// Attach handler implementations to the shared entrypoint declarations.
-elevate(sessionModules, session.base)
-elevate(sessionModules, session.list, handlers.list)
-elevate(sessionModules, session.add, handlers.add)
-elevate(sessionModules, session.remove, handlers.remove)
-
-export const appModules = [...modules, ...sessionModules]

package/template/sources/common/src/modules.ts

@@ -1,26 +0,0 @@
-import { body, entrypoint, filter, params } from '@owlmeans/entrypoint'
-import { route, RouteMethod } from '@owlmeans/route'
-import { session } from './consts.js'
-import { AddItemSchema, ItemParamsSchema, SessionParamsSchema } from './schemas.js'
-import type { AddItemPayload, ItemParams, SessionParams } from './types.js'
-
-/**
- * Shared entrypoint declarations. The api elevates these with handlers; the web
- * elevates them with screen components and calls them. Routes resolve under the
- * api service `base` (`/api`), so e.g. `session.list` → `GET /api/session/:sid/items`.
- */
-export const sessionModules = [
-  entrypoint(route(session.base, '/session')),
-  entrypoint(
-    route(session.list, '/:sid/items', { parent: session.base, method: RouteMethod.GET }),
-    filter(params<SessionParams>(SessionParamsSchema)),
-  ),
-  entrypoint(
-    route(session.add, '/:sid/items', { parent: session.base, method: RouteMethod.POST }),
-    filter(params<SessionParams>(SessionParamsSchema, body<AddItemPayload>(AddItemSchema))),
-  ),
-  entrypoint(
-    route(session.remove, '/:sid/items/:id', { parent: session.base, method: RouteMethod.DELETE }),
-    filter(params<ItemParams>(ItemParamsSchema)),
-  ),
-]

package/template/sources/web/src/components/nav/main.tsx

@@ -1,15 +0,0 @@
-import type { FC } from 'react'
-import { HOME, useNavigate } from '@owlmeans/web-panel'
-import { web } from '__APP_SLUG__-common'
-import { Button } from '@/components/ui/button'
-
-export const MainNavigation: FC = () => {
-  const nav = useNavigate()
-
-  return (
-    <nav className="flex items-center gap-1">
-      <Button variant="ghost" size="sm" onClick={nav.press(HOME)}>Home</Button>
-      <Button variant="ghost" size="sm" onClick={nav.press(web.session)}>Session</Button>
-    </nav>
-  )
-}

package/template/sources/web/src/modules.ts

@@ -1,20 +0,0 @@
-import { BASE, elevate, entrypoint, frontend, handler, HOME, modules as baseModules, route } from '@owlmeans/web-panel'
-import { session, sessionModules, web } from '__APP_SLUG__-common'
-import { MainLayout } from './layout/main.js'
-import { HomeScreen } from './screens/home.js'
-import { SessionScreen } from './screens/session.js'
-
-const modules = [...baseModules, ...sessionModules]
-
-// Backend entrypoints — elevated without a component so the client can call them.
-elevate(modules, session.base)
-elevate(modules, session.list)
-elevate(modules, session.add)
-elevate(modules, session.remove)
-
-// Frontend layout + screens. BASE renders the shared layout; HOME is its default child.
-modules.push(entrypoint(route(BASE, '/', frontend()), handler(MainLayout)))
-modules.push(entrypoint(route(HOME, '/', frontend({ default: true, parent: BASE })), handler(HomeScreen)))
-modules.push(entrypoint(route(web.session, '/session', frontend({ parent: BASE })), handler(SessionScreen)))
-
-export const appModules = modules