fse-theme-default 0.4.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.4.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/SettingsSections.astro

@@ -2,11 +2,14 @@
 /**
  * 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. A child theme overrides this file to put its own forms
- * here (a profile, preferences, ...) — the data comes from the app through
- * `FrameworkApp::page_context("settings", ...)`, and its POST handlers
- * re-render the page with `auth_module::settings_context`.
+ * 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";
 
@@ -25,3 +28,5 @@ const { t, first_name, last_name } = ssr<SettingsPage>();
   </div>
 </div>
 )}
+
+<Slot name="settings-sections" />

package/src/components/Sidebar.astro

@@ -1,10 +1,11 @@
 ---
 /**
  * The app shell's navigation. Everything is data-driven: the framework
- * injects `nav` (the models' sidebar entries — label, icon and order come
- * from `#[model(nav(...), public_nav(...))]` and the app's translations)
- * and `user`; links that aren't a model 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";
@@ -13,7 +14,7 @@ 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
@@ -72,10 +73,19 @@ const { t, nav, user, lang_prefix } = ssr<ShellContext>();
 
     <SidebarLinks />
 
-    {nav.map((item) => (
-      <NavLink href={`${lang_prefix}${item.href}`} label={item.label}>
-        <NavIcon name={item.icon} />
-      </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/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";
@@ -37,5 +40,7 @@ const { t, nav, user, lang_prefix } = ssr<ShellContext>();
         ))}
       </div>
     )}
+
+    <Slot name="dashboard" />
   </main>
 </Layout>

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. */
@@ -142,6 +158,19 @@ export interface NavItem {
   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). */
@@ -155,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."
 }