fse-theme-default 0.3.0 → 0.5.0

package/README.md

@@ -33,7 +33,8 @@ A child theme overrides any file under `src/` by creating the same path in
 its own `src/` — the parent's pages then use the child's version:
 
 - `src/layouts/Layout.astro` — the whole shell,
-- `src/components/SidebarLinks.astro` — app-specific sidebar entries (empty here),
+- `src/components/SidebarLinks.astro` — app-specific sidebar entries (renders
+  the `sidebar-links` slot; overriding it replaces every contribution),
 - `src/components/Logo.astro` — the logo in the sidebar, mobile header and
   auth pages (or replace just `src/assets/logo.svg`),
 - `src/components/Head.astro` — extra `<head>` tags on every page (favicon,
@@ -41,7 +42,23 @@ its own `src/` — the parent's pages then use the child's version:
 - `src/styles/global.css` — the Tailwind root (import `src/styles/theme.css`
   and override tokens after it).
 
-`@parent/...` imports the parent's original file (e.g. to wrap it).
+`@parent/...` imports the parent's original file (e.g. to wrap it);
+`@theme/...` the most specific theme's version of a file.
+
+### Slots
+
+Where several child themes and modules add to one place, the theme has a
+slot: every `src/slots/<slot>/<Name>.astro` of the child theme and of the
+app's modules is rendered there (this theme's first, modules next, the
+child last; a same-named file of a more specific layer replaces the other):
+
+- `sidebar-links` — sidebar entries between "Home" and the model links,
+- `settings-sections` — sections of the settings page (data through
+  `page_context("settings", ...)`),
+- `head` — extra `<head>` tags,
+- `dashboard` — widgets below the home page's model cards,
+- `record-panels` — panels below a generated record form (check
+  `meta.table`).
 
 ## Development
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fse-theme-default",
-  "version": "0.3.0",
-  "description": "Default theme for full_stack_engine apps — a complete Astro project: app shell, design system, auth pages, emails and the generic metadata-driven CRUD pages. Extend it with a child theme.",
+  "version": "0.5.0",
+  "description": "Default theme for full_stack_engine apps \u2014 a complete Astro project: app shell, design system, auth pages, emails and the generic metadata-driven CRUD pages. Extend it with a child theme.",
   "type": "module",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -25,7 +25,7 @@
   },
   "peerDependencies": {
     "astro": ">=7.0.0",
-    "fse-ssr": ">=0.2.0"
+    "fse-ssr": ">=0.3.0"
   },
   "devDependencies": {
     "@astrojs/check": "^0.9.9",

package/src/components/Head.astro

@@ -2,8 +2,12 @@
 /**
  * Extension point: extra <head> tags for every page (favicon, fonts, meta
  * tags). A child theme overrides this file; its version replaces this one,
- * so it should link its own favicon too.
+ * so it should link its own favicon too. Tags that only add (a module's
+ * stylesheet, a meta tag) go into the `head` slot instead:
+ * `src/slots/head/*.astro`.
  */
+import Slot from "fse-ssr/Slot.astro";
 ---
 
 <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+<Slot name="head" />

package/src/components/Logo.astro

@@ -2,16 +2,21 @@
 /**
  * Extension point: the logo shown in the sidebar, the mobile header and the
  * auth pages. A child theme either replaces src/assets/logo.svg or
- * overrides this file (e.g. separate light and dark images).
+ * overrides this file (e.g. separate light and dark images, other sizes per
+ * `variant`).
  */
 import { Image } from "astro:assets";
 import logo from "../assets/logo.svg";
 
 interface Props {
+  /** Where it is drawn; picks the default size. */
+  variant?: "sidebar" | "mobile" | "auth";
+  /** Replaces the variant's size classes entirely. */
   class?: string;
 }
 
-const { class: className = "h-9 w-auto" } = Astro.props;
+const sizes = { sidebar: "h-9 w-auto", mobile: "h-8 w-auto", auth: "h-12 w-auto" };
+const { variant = "sidebar", class: className } = Astro.props;
 ---
 
-<Image src={logo} alt="Logo" class={className} />
+<Image src={logo} alt="Logo" class={className ?? sizes[variant]} />

package/src/components/NavIcon.astro

@@ -0,0 +1,48 @@
+---
+/**
+ * The named 18px icons sidebar entries use. A model picks one with
+ * `#[model(nav(icon = "heart"))]` (or `public_nav(...)`); the framework sends
+ * `table` when it names none. An unknown name draws nothing — add it here
+ * (or in a child theme's override of this file).
+ *
+ * home, grid, calendar, heart, run, user, users, settings, table, list,
+ * box, cart, file, chart, tag, mail, map-pin, star
+ */
+import type { SsrValue } from "fse-ssr/ssr";
+
+interface Props {
+  name: string | SsrValue<string>;
+}
+
+const { name } = Astro.props;
+const a = {
+  xmlns: "http://www.w3.org/2000/svg",
+  width: "18",
+  height: "18",
+  viewBox: "0 0 24 24",
+  fill: "none",
+  stroke: "currentColor",
+  "stroke-width": "1.5",
+  "stroke-linecap": "round",
+  "stroke-linejoin": "round",
+} as const;
+---
+
+{name === "home" && (<svg {...a}><path d="M3 10.5 12 3l9 7.5"></path><path d="M5 9.5V21h14V9.5"></path><path d="M10 21v-6h4v6"></path></svg>)}
+{name === "grid" && (<svg {...a}><rect width="7.5" height="7.5" x="2.75" y="2.75" rx="1.9"></rect><rect width="7.5" height="7.5" x="13.75" y="2.75" rx="1.9"></rect><rect width="7.5" height="7.5" x="13.75" y="13.75" rx="1.9"></rect><rect width="7.5" height="7.5" x="2.75" y="13.75" rx="1.9"></rect></svg>)}
+{name === "calendar" && (<svg {...a}><rect width="18" height="18" x="3" y="4" rx="2" ry="2"></rect><path d="M16 2v4M8 2v4m-5 4h18"></path></svg>)}
+{name === "heart" && (<svg {...a}><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"></path></svg>)}
+{name === "run" && (<svg {...a}><path d="M13 4a1 1 0 1 0 2 0 1 1 0 0 0-2 0"></path><path d="m7 21 3-6 2 2 3-4 3 8"></path><path d="m5 14 2-5 5 1 2-4"></path></svg>)}
+{name === "user" && (<svg {...a}><circle cx="12" cy="7" r="4"></circle><path d="M5 21v-2a7 7 0 0 1 14 0v2"></path></svg>)}
+{name === "users" && (<svg {...a}><circle cx="9" cy="7" r="4"></circle><path d="M3 21v-2a6 6 0 0 1 12 0v2"></path><path d="M16 3.13a4 4 0 0 1 0 7.75M21 21v-2a6 6 0 0 0-4-5.66"></path></svg>)}
+{name === "settings" && (<svg {...a}><circle cx="12" cy="12" r="3"></circle><path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09a1.65 1.65 0 0 0-1-1.51 1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09a1.65 1.65 0 0 0 1.51-1 1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9c.26.6.85 1 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z"></path></svg>)}
+{name === "table" && (<svg {...a}><rect width="18" height="18" x="3" y="3" rx="2"></rect><path d="M3 9h18M9 21V9"></path></svg>)}
+{name === "list" && (<svg {...a}><path d="M8 6h13M8 12h13M8 18h13M3 6h.01M3 12h.01M3 18h.01"></path></svg>)}
+{name === "box" && (<svg {...a}><path d="M21 8 12 3 3 8v8l9 5 9-5z"></path><path d="m3 8 9 5 9-5M12 13v8"></path></svg>)}
+{name === "cart" && (<svg {...a}><circle cx="9" cy="20" r="1"></circle><circle cx="18" cy="20" r="1"></circle><path d="M2 3h3l2.7 12.4a2 2 0 0 0 2 1.6h7.6a2 2 0 0 0 2-1.6L21 7H6"></path></svg>)}
+{name === "file" && (<svg {...a}><path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><path d="M14 3v6h6M8 13h8M8 17h5"></path></svg>)}
+{name === "chart" && (<svg {...a}><path d="M3 3v18h18"></path><path d="M7 15v2M12 10v7M17 6v11"></path></svg>)}
+{name === "tag" && (<svg {...a}><path d="M20.6 13.4 13.4 20.6a2 2 0 0 1-2.8 0L3 13V3h10l7.6 7.6a2 2 0 0 1 0 2.8z"></path><circle cx="7.5" cy="7.5" r="1.5"></circle></svg>)}
+{name === "mail" && (<svg {...a}><rect width="18" height="14" x="3" y="5" rx="2"></rect><path d="m3 7 9 6 9-6"></path></svg>)}
+{name === "map-pin" && (<svg {...a}><path d="M20 10c0 6-8 12-8 12s-8-6-8-12a8 8 0 0 1 16 0z"></path><circle cx="12" cy="10" r="3"></circle></svg>)}
+{name === "star" && (<svg {...a}><path d="m12 2 3.1 6.3 6.9 1-5 4.9 1.2 6.8L12 17.8 5.8 21l1.2-6.8-5-4.9 6.9-1z"></path></svg>)}

package/src/components/SettingsSections.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * Extension point: the app's own sections of the settings page, rendered
+ * between "account security" and "delete account". The default shows the
+ * account's name, followed by the `settings-sections` slot: every
+ * `src/slots/settings-sections/*.astro` of a child theme or a module (a
+ * profile, preferences, ...). Their data comes through
+ * `page_context("settings", ...)` (app or module), and POST handlers
+ * re-render the page with `auth_module::settings_context`. Overriding this
+ * file replaces the default and every contribution.
+ */
+import Slot from "fse-ssr/Slot.astro";
+import { ssr } from "fse-ssr/ssr";
+import type { SettingsPage } from "../types/pages";
+
+const { t, first_name, last_name } = ssr<SettingsPage>();
+---
+
+{(first_name || last_name) && (
+<div class="py-6">
+  <h3 class="text-base font-semibold text-secondary-900">
+    {t.settings.name}
+  </h3>
+  <div class="mt-3 px-4 py-3 rounded-lg bg-secondary-50 border border-secondary-100">
+    <span class="text-sm font-medium text-secondary-900">
+      {first_name} {last_name}
+    </span>
+  </div>
+</div>
+)}
+
+<Slot name="settings-sections" />

package/src/components/Sidebar.astro

@@ -1,16 +1,20 @@
 ---
 /**
  * The app shell's navigation. Everything is data-driven: the framework
- * injects `nav` (the admin page of every model the user may read) and
- * `user`; app-specific links come from the SidebarLinks extension point.
+ * injects `nav_groups` (the models' sidebar entries — label, icon and order
+ * come from `#[model(nav(...), public_nav(...))]` and the app's
+ * translations — grouped by module, each module's under its title) and
+ * `user`; links that aren't a model come from the SidebarLinks extension
+ * point.
  */
 import { ssr } from "fse-ssr/ssr";
 import Logo from "./Logo.astro";
+import NavIcon from "./NavIcon.astro";
 import NavLink from "./NavLink.astro";
 import SidebarLinks from "./SidebarLinks.astro";
 import type { ShellContext } from "../types";
 
-const { t, nav, user, lang_prefix } = ssr<ShellContext>();
+const { t, nav_groups, user, lang_prefix } = ssr<ShellContext>();
 ---
 
 <div
@@ -33,7 +37,7 @@ const { t, nav, user, lang_prefix } = ssr<ShellContext>();
       class="sidebar-full-logo flex items-center gap-2 focus:outline-hidden focus-visible:ring-2 focus-visible:ring-primary-500 rounded-md"
       href={`${lang_prefix}/`}
     >
-      <Logo class="h-9 w-auto" />
+      <Logo variant="sidebar" />
     </a>
 
     <button
@@ -69,12 +73,19 @@ const { t, nav, user, lang_prefix } = ssr<ShellContext>();
 
     <SidebarLinks />
 
-    {nav.map((item) => (
-      <NavLink href={`${lang_prefix}${item.href}`} label={t.models[item.table].title ?? item.table}>
-        <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
-          <rect width="18" height="18" x="3" y="3" rx="2"></rect><path d="M3 9h18M9 21V9"></path>
-        </svg>
-      </NavLink>
+    {nav_groups.map((group) => (
+      <div class="space-y-0.5">
+        {group.label && (
+          <p class="sidebar-label px-3 pt-4 pb-1 text-xs font-semibold uppercase tracking-wide text-secondary-400 truncate">
+            {group.label}
+          </p>
+        )}
+        {group.entries.map((item) => (
+          <NavLink href={`${lang_prefix}${item.href}`} label={item.label}>
+            <NavIcon name={item.icon} />
+          </NavLink>
+        ))}
+      </div>
     ))}
   </nav>
 

package/src/components/SidebarLinks.astro

@@ -1,10 +1,17 @@
 ---
 /**
  * Extension point: app-specific sidebar entries, rendered between "Home"
- * and the generated model links. Empty in the default theme — a child theme
- * overrides this file (same path under its src/) to add its own links:
+ * and the generated model links. Filled through the `sidebar-links` slot:
+ * every `src/slots/sidebar-links/*.astro` of a child theme or a module is
+ * rendered here, so several can add links side by side:
  *
- *   import NavLink from "@parent/components/NavLink.astro";
+ *   // src/slots/sidebar-links/Products.astro
+ *   import NavLink from "@theme/components/NavLink.astro";
  *   <NavLink href="/products" label={t.nav.products}>…icon…</NavLink>
+ *
+ * Overriding this file instead replaces every contribution.
  */
+import Slot from "fse-ssr/Slot.astro";
 ---
+
+<Slot name="sidebar-links" />

package/src/layouts/Layout.astro

@@ -73,7 +73,7 @@ const { lang } = ssr();
                 <line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line>
               </svg>
             </button>
-            <a href="/"><Logo class="h-8 w-auto" /></a>
+            <a href="/"><Logo variant="mobile" /></a>
           </div>
         )}
         <slot />

package/src/pages/forgot-password.astro

@@ -14,7 +14,7 @@ const messages = t.messages as Record<string, string>;
     <div class="w-full max-w-sm">
       <div class="flex justify-center mb-8">
         <a href="/">
-          <Logo class="h-12 w-auto" />
+          <Logo variant="auth" />
         </a>
       </div>
 

package/src/pages/fse/form.astro

@@ -7,13 +7,19 @@
  * row) the same form renders disabled and without a save button. An
  * existing row also shows its allowed row actions and links to its nested
  * models and link tables; a nested model links back to its parent row.
+ * Below the form: `related` — the rows of other models (and modules)
+ * that point at this one through a foreign key, one panel each — then the
+ * `record-panels` slot: extra panels from a child theme or modules
+ * (`src/slots/record-panels/*.astro`, which check `meta.table` to pick the
+ * models they extend).
  */
+import Slot from "fse-ssr/Slot.astro";
 import { ssr } from "fse-ssr/ssr";
 import type { SsrValue } from "fse-ssr/ssr";
 import Layout from "../../layouts/Layout.astro";
 import type { ModelFormPage } from "../../types";
 
-const { t, lang_prefix, meta, row, errors, is_new, can_edit, can_delete, actions, parent } =
+const { t, lang_prefix, meta, row, errors, is_new, can_edit, can_delete, actions, parent, related } =
   ssr<ModelFormPage>();
 const title = t.models[meta.table].title ?? meta.table;
 const formErrors = t.form_errors as Record<string, SsrValue<string>>;
@@ -155,6 +161,32 @@ const inputClass =
         ))}
       </div>
     )}
+
+    {related.map((panel) => (
+      <section class="mt-8">
+        <h2 class="mb-2 text-base font-semibold text-secondary-900">
+          {t.models[panel.table].title ?? panel.table}
+          {panel.label_column && (
+            <span class="font-normal text-secondary-500"> · {t.models[panel.table].fields[panel.label_column] ?? panel.label_column}</span>
+          )}
+          <span class="ml-1 text-sm font-normal text-secondary-500">({panel.total})</span>
+        </h2>
+        <ul class="divide-y divide-secondary-100 rounded-lg border border-secondary-100 bg-white">
+          {panel.rows.map((item) => (
+            <li>
+              <a class="block px-4 py-2 text-sm text-secondary-800 hover:bg-secondary-50" href={`${lang_prefix}${panel.base_path}/${item.id}`}>
+                {item.title}
+              </a>
+            </li>
+          ))}
+        </ul>
+        {panel.more && (
+          <p class="mt-1 text-xs text-secondary-500">{t.model_ui.more_related ?? "Showing the first 10."}</p>
+        )}
+      </section>
+    ))}
+
+    <Slot name="record-panels" />
   </main>
 
   <script>

package/src/pages/index.astro

@@ -1,8 +1,11 @@
 ---
 /**
- * Default home page: a dashboard linking every model the user may manage.
- * Apps usually replace it (a child theme's own src/pages/index.astro).
+ * Default home page: a dashboard linking every model the user may manage,
+ * then the `dashboard` slot (widgets from a child theme or modules:
+ * `src/slots/dashboard/*.astro`). Apps usually replace it (a child theme's
+ * own src/pages/index.astro).
  */
+import Slot from "fse-ssr/Slot.astro";
 import { ssr } from "fse-ssr/ssr";
 import Card from "../components/Card.astro";
 import Header from "../components/Header.astro";
@@ -30,12 +33,14 @@ const { t, nav, user, lang_prefix } = ssr<ShellContext>();
         {nav.map((item) => (
           <a href={`${lang_prefix}${item.href}`}>
             <Card accent="primary" hover>
-              <h2 class="text-lg font-bold text-secondary-900">{t.models[item.table].title ?? item.table}</h2>
+              <h2 class="text-lg font-bold text-secondary-900">{item.label}</h2>
               <p class="text-sm text-secondary-500">{t.dashboard.manage ?? "Manage entries"}</p>
             </Card>
           </a>
         ))}
       </div>
     )}
+
+    <Slot name="dashboard" />
   </main>
 </Layout>

package/src/pages/login.astro

@@ -16,7 +16,7 @@ const messages = t.messages as Record<string, string>;
       <!-- Logo -->
       <div class="flex justify-center mb-8">
         <a href="/">
-          <Logo class="h-12 w-auto" />
+          <Logo variant="auth" />
         </a>
       </div>
 

package/src/pages/register.astro

@@ -14,7 +14,7 @@ const errors = t.errors as Record<string, string>;
       <!-- Logo -->
       <div class="flex justify-center mb-8">
         <a href="/">
-          <Logo class="h-12 w-auto" />
+          <Logo variant="auth" />
         </a>
       </div>
 

package/src/pages/settings.astro

@@ -5,13 +5,12 @@ import Card from "../components/Card.astro";
 import Header from "../components/Header.astro";
 import Input from "../components/Input.astro";
 import Modal from "../components/Modal.astro";
+import SettingsSections from "../components/SettingsSections.astro";
 import type { SettingsPage } from "../types/pages";
 
 const {
   t,
   current_email,
-  first_name,
-  last_name,
   success,
   error,
   email_success,
@@ -29,20 +28,6 @@ const errors = t.errors as Record<string, string>;
     <Card>
       <div class="flex flex-col divide-y divide-secondary-100">
 
-        <!-- Name -->
-        {(first_name || last_name) && (
-        <div class="pb-6">
-          <h3 class="text-base font-semibold text-secondary-900">
-            {t.settings.name}
-          </h3>
-          <div class="mt-3 px-4 py-3 rounded-lg bg-secondary-50 border border-secondary-100">
-            <span class="text-sm font-medium text-secondary-900">
-              {first_name} {last_name}
-            </span>
-          </div>
-        </div>
-        )}
-
         <!-- Email Setting -->
         <div class="py-6 first:pt-0">
           <div class="flex items-start justify-between mb-3 flex-wrap gap-2">
@@ -89,6 +74,9 @@ const errors = t.errors as Record<string, string>;
           )}
         </div>
 
+        <!-- The app's sections (default: the account's name) -->
+        <SettingsSections />
+
         <!-- Danger Zone -->
         <div class="pt-6">
           <div class="flex items-start justify-between flex-wrap gap-3">

package/src/pages/user.astro

@@ -56,7 +56,7 @@ const roleLabels = t.roles as Record<string, string>;
         <!-- Actions -->
         <div class="flex sm:justify-end pt-5 border-t border-secondary-100">
           <button type="submit" class="btn-primary w-full sm:w-auto">
-            <span>{t.common.save}</span>
+            <span>{t.users.save}</span>
           </button>
         </div>
       </form>

package/src/types.ts

@@ -116,6 +116,22 @@ export interface ModelFormPage {
   actions: string[];
   /** The parent row, for a nested model (else null). */
   parent: ParentContext | null;
+  /** Rows of other models (and modules) pointing at this one. */
+  related: RelatedPanel[];
+}
+
+/**
+ * One model's rows that point at a record through a foreign key — the
+ * first ten, with `more` when there are others.
+ */
+export interface RelatedPanel {
+  table: string;
+  base_path: string;
+  /** Set when the model points here through several columns. */
+  label_column: string | null;
+  total: number;
+  more: boolean;
+  rows: { id: number; title: string }[];
 }
 
 /** `fse/links` — the rows of another model linked to one row. */
@@ -136,6 +152,25 @@ export interface ModelDetailPage {
 export interface NavItem {
   table: string;
   href: string;
+  /** Already translated (`t.models.<table>.nav` / `.public_nav` / `.title`). */
+  label: string;
+  /** A `NavIcon` name. */
+  icon: string;
+  /** The public list's entry rather than the admin page. */
+  public: boolean;
+  /** The cargo package defining the model (the app's or a module's). */
+  krate: string;
+}
+
+/**
+ * `nav` grouped by origin: the app's own models first (`module` and
+ * `label` null), then one group per enabled module, labelled
+ * `t.modules.<package>.title`.
+ */
+export interface NavGroup {
+  module: string | null;
+  label: string | null;
+  entries: NavItem[];
 }
 
 /** The signed-in user as injected by the framework (absent when signed out). */
@@ -149,6 +184,7 @@ export interface SessionUser {
 /** Context keys every page receives, whatever renders it. */
 export interface ShellContext {
   nav: NavItem[];
+  nav_groups: NavGroup[];
   user?: SessionUser;
   lang_prefix: string;
 }

package/theme.json

@@ -1,5 +1,5 @@
 {
   "name": "fse-theme-default",
-  "version": "0.2.1",
+  "version": "0.5.0",
   "description": "Default full_stack_engine theme: app shell, design system, auth pages, emails and the generic model CRUD pages."
 }