@viniaraujo68/plinth 0.3.0 → 0.5.0

package/dist/shell/AppShell.svelte

@@ -6,10 +6,10 @@
   import { untrack, type Snippet } from "svelte";
   import type { ClassValue } from "svelte/elements";
   import Dialog from "../components/Dialog.svelte";
-  import { PICK_CLIP_PATH } from "../components/pick.js";
   import { tooltip } from "../attachments/tooltip.js";
   import { getRoutingContext, resolvePathname, type ResolvedRoute } from "../routing.svelte.js";
   import { getUserContext, type UserData } from "../user/context.js";
+  import UserAvatar from "./UserAvatar.svelte";
 
   interface Props {
     /** The routed page. The shell owns the scroll container around it. */
@@ -51,6 +51,7 @@
     closeLabel?: string;
     /** Label of the sign-out control, which only appears when the user context can sign out. */
     logoutLabel?: string;
+    overviewLabel?: string;
   }
 
   /**
@@ -82,12 +83,23 @@
     moreLabel = "More",
     closeLabel = "Close",
     logoutLabel = "Sign out",
+    overviewLabel = "Overview",
   }: Props = $props();
 
+  const uid = $props.id();
+
   const routing = getRoutingContext();
   const user = getUserContext();
 
-  const listed = (route: ResolvedRoute) => route.meta.title !== undefined && route.navigable;
+  const titled = (route: ResolvedRoute) => route.meta.title !== undefined;
+  const listed = (route: ResolvedRoute) => titled(route) && route.navigable;
+  const inScope = (route: ResolvedRoute) => user.hasAnyRole(route.meta.requiredRoles ?? []);
+  const isStatic = (route: ResolvedRoute) => route.pathname === route.routeId;
+
+  interface NavEntry {
+    route: ResolvedRoute;
+    children: ResolvedRoute[];
+  }
 
   /**
    * Home is the header entry, apart from the list — derived, never re-declared. The root is a
@@ -102,10 +114,17 @@
    * overflow. Wrapping each item in the component would leave the slot arithmetic counting entries
    * the user never sees, and "More" opening onto an empty sheet.
    */
-  const items = $derived(
+  const entries: NavEntry[] = $derived(
     routing
       .children("/")
-      .filter((route) => listed(route) && user.hasAnyRole(route.meta.requiredRoles ?? [])),
+      .filter((route) => titled(route) && inScope(route))
+      .map((route) => ({
+        route,
+        children: routing
+          .children(route.routeId)
+          .filter((child) => listed(child) && isStatic(child) && inScope(child)),
+      }))
+      .filter((entry) => entry.route.navigable || entry.children.length > 0),
   );
 
   /**
@@ -122,6 +141,33 @@
       ? routing.routeId === "/"
       : routing.matched.some((match) => match.routeId === route.routeId);
 
+  const isOverviewCurrent = (entry: NavEntry) =>
+    isCurrent(entry.route) && !entry.children.some(isCurrent);
+
+  let openGroups = $state<Record<string, boolean>>({});
+  const isOpen = (route: ResolvedRoute) => openGroups[route.routeId] ?? isCurrent(route);
+
+  const enteredGroup = $derived(
+    entries.find((entry) => entry.children.length > 0 && isCurrent(entry.route))?.route.routeId,
+  );
+
+  $effect(() => {
+    const id = enteredGroup;
+    if (id === undefined) return;
+    untrack(() => {
+      openGroups[id] = true;
+    });
+  });
+
+  const toggleGroup = (route: ResolvedRoute) => {
+    if (collapsed) {
+      collapsed = false;
+      openGroups[route.routeId] = true;
+      return;
+    }
+    openGroups[route.routeId] = !isOpen(route);
+  };
+
   let content: HTMLElement | undefined = $state();
   const offsets: Record<string, number> = {};
   let returningTo: string | null = null;
@@ -152,7 +198,11 @@
   });
 
   // Home leads the bottom bar rather than heading it: a bar has no header to put it in.
-  const barEntries = $derived(home ? [home, ...items] : items);
+  const navigableTopLevel = $derived(
+    entries.filter((entry) => entry.route.navigable).map((entry) => entry.route),
+  );
+  const barEntries = $derived(home ? [home, ...navigableTopLevel] : navigableTopLevel);
+  const hasGroups = $derived(entries.some((entry) => entry.children.length > 0));
   const slots = $derived(Math.max(1, bottomBarSlots));
 
   const signedInUser = $derived(user.status === "authenticated" ? user.data : null);
@@ -165,7 +215,7 @@
   const sheetChrome = $derived(
     brand !== undefined || footer !== undefined || signedInUser !== null,
   );
-  const showMore = $derived(barEntries.length > slots || sheetChrome);
+  const showMore = $derived(barEntries.length > slots || sheetChrome || hasGroups);
 
   /*
    * Slot arithmetic. `bottomBarSlots` caps what the bar renders, "More" counted among it, so the
@@ -184,22 +234,14 @@
   const navSlots = $derived(showMore ? slots - 1 : slots);
   const barItems = $derived(barEntries.slice(0, navSlots));
   const overflowItems = $derived(barEntries.slice(navSlots));
+  const overflowed = (route: ResolvedRoute) =>
+    overflowItems.some((item) => item.routeId === route.routeId);
 
-  const initials = (name: string) => {
-    const words = name.split(/\s+/).filter(Boolean);
-    if (words.length === 0) return "?";
-    const first = words[0][0];
-    const last = words.length > 1 ? words[words.length - 1][0] : "";
-    return `${first}${last}`.toUpperCase();
-  };
-
-  /* Per instance, not a constant: a page can mount two shells against one routing context — the
-     showcase mounts exactly two — and a duplicated id would point both avatars at whichever
-     `<clipPath>` the parser saw first. */
-  const avatarClip = $props.id();
-  // The sidebar and the sheet render the same user block, and while the sheet is open both are in
-  // the document: two `<clipPath>` definitions, so two ids.
-  const sheetAvatarClip = `${avatarClip}-sheet`;
+  const sheetEntries: NavEntry[] = $derived(
+    [...(home ? [{ route: home, children: [] }] : []), ...entries].filter(
+      (entry) => entry.children.length > 0 || overflowed(entry.route),
+    ),
+  );
 
   let sheet = $state<Dialog>();
 
@@ -225,14 +267,14 @@ and because the root is its own container, the shell can be dropped into a narro
 mobile form on a desktop, which is exactly what the showcase does.
 
 Entries come from `routing.children("/")`, minus plumbing (no `title`), minus any route with no page
-of its own to link to, and minus anything the user context gates out. Home, when declared, is derived off the trail and rendered as the sidebar's
+of its own to link to (unless it heads a group), and minus anything the user context gates out. Home, when declared, is derived off the trail and rendered as the sidebar's
 header entry and as the bottom bar's first item. It is current on the exact root and nowhere else —
 every route is below it — while every other entry is current for its whole subtree, so exactly one
 entry is ever marked, in either form.
 
 The bar form has no sidebar, and so no brand, no footer and no user block. All three move into the
 sheet behind the "More" item, which is therefore shown whenever there is anything to put there —
-overflowing entries, a `brand` snippet, a `footer` snippet or a signed-in user — and not only on an
+overflowing entries, a group's children, a `brand` snippet, a `footer` snippet or a signed-in user — and not only on an
 overflow. The sheet reads brand, then the entries that did not fit, then `footer`, then the user
 block with its sign-out control. Choosing an entry dismisses it; using a footer control does not.
 
@@ -301,17 +343,73 @@ shell rather than to the window, and the content area reserves its height plus
 
     <nav class="sidebar-nav" aria-label={navLabel}>
       <ul>
-        {#each items as item (item.routeId)}
+        {#each entries as entry, index (entry.route.routeId)}
+          {@const item = entry.route}
           <li>
-            <a
-              class="nav-link"
-              href={resolvePathname(item.pathname)}
-              aria-current={isCurrent(item) ? "page" : undefined}
-              {@attach tooltip(item.label, { disabled: !collapsed })}
-            >
-              <span class="nav-icon">{@render routeIcon(item)}</span>
-              <span class="nav-label collapsible">{item.label}</span>
-            </a>
+            {#if entry.children.length > 0}
+              {@const foldId = `${uid}-group-${index}`}
+              <button
+                type="button"
+                class={["nav-link nav-group", isCurrent(item) && "has-current"]}
+                aria-expanded={!collapsed && isOpen(item)}
+                aria-controls={foldId}
+                onclick={() => toggleGroup(item)}
+                {@attach tooltip(item.label, { disabled: !collapsed })}
+              >
+                <span class="nav-icon">{@render routeIcon(item)}</span>
+                <span class="nav-label collapsible">{item.label}</span>
+                <svg
+                  class="nav-chevron collapsible"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  stroke-width="2"
+                  stroke-linecap="round"
+                  stroke-linejoin="round"
+                  aria-hidden="true"
+                >
+                  <path d="m9 18 6-6-6-6" />
+                </svg>
+              </button>
+              <div id={foldId} class={["nav-fold", isOpen(item) && "open"]} inert={!isOpen(item)}>
+                <div>
+                  <ul>
+                    {#if item.navigable}
+                      <li>
+                        <a
+                          class="nav-link nav-sublink"
+                          href={resolvePathname(item.pathname)}
+                          aria-current={isOverviewCurrent(entry) ? "page" : undefined}
+                        >
+                          <span class="nav-label">{overviewLabel}</span>
+                        </a>
+                      </li>
+                    {/if}
+                    {#each entry.children as child (child.routeId)}
+                      <li>
+                        <a
+                          class="nav-link nav-sublink"
+                          href={resolvePathname(child.pathname)}
+                          aria-current={isCurrent(child) ? "page" : undefined}
+                        >
+                          <span class="nav-label">{child.label}</span>
+                        </a>
+                      </li>
+                    {/each}
+                  </ul>
+                </div>
+              </div>
+            {:else}
+              <a
+                class="nav-link"
+                href={resolvePathname(item.pathname)}
+                aria-current={isCurrent(item) ? "page" : undefined}
+                {@attach tooltip(item.label, { disabled: !collapsed })}
+              >
+                <span class="nav-icon">{@render routeIcon(item)}</span>
+                <span class="nav-label collapsible">{item.label}</span>
+              </a>
+            {/if}
           </li>
         {/each}
       </ul>
@@ -323,7 +421,7 @@ shell rather than to the window, and the content area reserves its height plus
       {/if}
 
       {#if signedInUser}
-        {@render userBlock(signedInUser, avatarClip)}
+        {@render userBlock(signedInUser)}
       {/if}
     </div>
   </aside>
@@ -387,20 +485,57 @@ shell rather than to the window, and the content area reserves its height plus
       </button>
     </div>
     <div class="sheet-body">
-      {#if overflowItems.length > 0}
+      {#if sheetEntries.length > 0}
         <ul class="sheet-list">
-          {#each overflowItems as item (item.routeId)}
-            <li>
-              <a
-                class="sheet-link"
-                href={resolvePathname(item.pathname)}
-                aria-current={isCurrent(item) ? "page" : undefined}
-                onclick={() => sheet?.close()}
-              >
-                <span class="nav-icon">{@render routeIcon(item)}</span>
-                <span>{item.label}</span>
-              </a>
-            </li>
+          {#each sheetEntries as entry, index (entry.route.routeId)}
+            {@const item = entry.route}
+            {#if entry.children.length > 0}
+              {@const headingId = `${uid}-sheet-group-${index}`}
+              <li class="sheet-group">
+                <p class="sheet-heading" id={headingId}>
+                  <span class="nav-icon">{@render routeIcon(item)}</span>
+                  <span>{item.label}</span>
+                </p>
+                <ul aria-labelledby={headingId}>
+                  {#if item.navigable && overflowed(item)}
+                    <li>
+                      <a
+                        class="sheet-link sheet-sublink"
+                        href={resolvePathname(item.pathname)}
+                        aria-current={isOverviewCurrent(entry) ? "page" : undefined}
+                        onclick={() => sheet?.close()}
+                      >
+                        {overviewLabel}
+                      </a>
+                    </li>
+                  {/if}
+                  {#each entry.children as child (child.routeId)}
+                    <li>
+                      <a
+                        class="sheet-link sheet-sublink"
+                        href={resolvePathname(child.pathname)}
+                        aria-current={isCurrent(child) ? "page" : undefined}
+                        onclick={() => sheet?.close()}
+                      >
+                        {child.label}
+                      </a>
+                    </li>
+                  {/each}
+                </ul>
+              </li>
+            {:else}
+              <li>
+                <a
+                  class="sheet-link"
+                  href={resolvePathname(item.pathname)}
+                  aria-current={isCurrent(item) ? "page" : undefined}
+                  onclick={() => sheet?.close()}
+                >
+                  <span class="nav-icon">{@render routeIcon(item)}</span>
+                  <span>{item.label}</span>
+                </a>
+              </li>
+            {/if}
           {/each}
         </ul>
       {/if}
@@ -414,26 +549,15 @@ shell rather than to the window, and the content area reserves its height plus
       {/if}
 
       {#if signedInUser}
-        <div class="sheet-user">{@render userBlock(signedInUser, sheetAvatarClip)}</div>
+        <div class="sheet-user">{@render userBlock(signedInUser)}</div>
       {/if}
     </div>
   </Dialog>
 </div>
 
-{#snippet userBlock(data: UserData, clipId: string)}
+{#snippet userBlock(data: UserData)}
   <div class="user-card">
-    <!-- A `<clipPath>` rather than CSS `clip-path: path()`, because `path()` takes user units and
-         never scales: it would fit one avatar size and no other.
-         `clipPathUnits="objectBoundingBox"` reads the same outline in 0..1 and follows whatever
-         box the span turns out to be. -->
-    <svg class="avatar-clip" aria-hidden="true" focusable="false">
-      <clipPath id={clipId} clipPathUnits="objectBoundingBox">
-        <path d={PICK_CLIP_PATH} />
-      </clipPath>
-    </svg>
-    <span class="avatar-initials" aria-hidden="true" style:clip-path="url(#{clipId})">
-      {initials(data.name)}
-    </span>
+    <UserAvatar name={data.name} />
     <span class="user-identity collapsible">
       <span class="user-name">{data.name}</span>
       <span class="user-email">{data.email}</span>
@@ -610,8 +734,10 @@ shell rather than to the window, and the content area reserves its height plus
     flex-shrink: 0;
     align-items: center;
     justify-content: center;
-    /* The icon column is exactly the collapsed width, so collapsing moves nothing. */
-    width: var(--plinth-sidebar-collapsed-width);
+    /* The icon column is exactly what the collapsed rail has inside its 1px border, so collapsing
+       moves nothing. The full collapsed width would overhang that border by a pixel, which the
+       nav, scrolling vertically, turns into a sideways scrollbar under the icons. */
+    width: calc(var(--plinth-sidebar-collapsed-width) - 1px);
     font-size: 1.25rem;
   }
 
@@ -636,6 +762,61 @@ shell rather than to the window, and the content area reserves its height plus
     color: var(--color-primary);
   }
 
+  .nav-group {
+    width: 100%;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    background: none;
+    font: inherit;
+    text-align: start;
+    cursor: pointer;
+  }
+
+  .nav-group.has-current {
+    color: var(--color-base-content);
+  }
+
+  .nav-group.has-current .nav-icon {
+    color: var(--color-primary);
+  }
+
+  .nav-chevron {
+    flex-shrink: 0;
+    width: 1rem;
+    height: 1rem;
+    margin-inline: auto 0.75rem;
+    transition: transform 200ms ease;
+  }
+
+  .nav-group[aria-expanded="true"] .nav-chevron {
+    transform: rotate(90deg);
+  }
+
+  .nav-fold {
+    display: grid;
+    grid-template-rows: 0fr;
+    transition: grid-template-rows 200ms ease;
+  }
+
+  .nav-fold.open {
+    grid-template-rows: 1fr;
+  }
+
+  .nav-fold > div {
+    min-height: 0;
+    overflow: hidden;
+  }
+
+  .plinth-shell.collapsed .shell-sidebar .nav-fold {
+    display: none;
+  }
+
+  .nav-sublink {
+    height: 2.25rem;
+    padding-inline-start: calc(var(--plinth-sidebar-collapsed-width) - 1px);
+  }
+
   .sidebar-footer {
     border-top: 1px solid var(--plinth-shell-line);
   }
@@ -654,37 +835,6 @@ shell rather than to the window, and the content area reserves its height plus
     padding: 0.625rem;
   }
 
-  /* Carries the definition only; the shape is painted by the span that references it. Zero-sized
-     rather than `display: none`, which is the one way of hiding it that some engines take as
-     licence to skip the subtree the reference needs. */
-  .avatar-clip {
-    position: absolute;
-    width: 0;
-    height: 0;
-  }
-
-  .avatar-initials {
-    display: flex;
-    flex-shrink: 0;
-    align-items: center;
-    justify-content: center;
-    /* Wider than the circle it replaces: the outline is inset inside its own 32-unit square, so
-       the pick drawn in a 2rem box would have come out visibly smaller than the disc did. */
-    width: 2.5rem;
-    height: 2.5rem;
-    /* The silhouette tapers to a point at the top, which puts its mass below the middle of the
-       box. A few pixels of head room is what centres the initials in the shape rather than in the
-       box that contains it. */
-    padding-top: 0.25rem;
-    /* Solid, where the disc was a 15% wash: a clipped shape is only readable by its edge, and a
-       wash that faint leaves the edge to guesswork. `--color-primary-content` is the pair the
-       theme guarantees against it in both modes. */
-    background-color: var(--color-primary);
-    color: var(--color-primary-content);
-    font-size: 0.75rem;
-    font-weight: 500;
-  }
-
   .user-identity {
     display: flex;
     flex: 1;
@@ -852,6 +1002,28 @@ shell rather than to the window, and the content area reserves its height plus
     background-color: var(--color-base-300);
   }
 
+  .sheet-group ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .sheet-heading {
+    display: flex;
+    align-items: center;
+    min-height: 2.75rem;
+    margin: 0;
+    color: color-mix(in oklch, var(--color-base-content) 60%, transparent);
+    font-size: 0.75rem;
+    font-weight: 600;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+
+  .sheet-sublink {
+    padding-inline-start: calc(var(--plinth-sidebar-collapsed-width) - 1px);
+  }
+
   @container plinth-shell (min-width: 48rem) {
     .shell-sidebar {
       display: flex;
@@ -867,7 +1039,9 @@ shell rather than to the window, and the content area reserves its height plus
   }
 
   @media (prefers-reduced-motion: reduce) {
-    .shell-sidebar {
+    .shell-sidebar,
+    .nav-chevron,
+    .nav-fold {
       transition: none;
     }
   }

package/dist/shell/AppShell.svelte.d.ts

@@ -43,6 +43,7 @@ interface Props {
     closeLabel?: string;
     /** Label of the sign-out control, which only appears when the user context can sign out. */
     logoutLabel?: string;
+    overviewLabel?: string;
 }
 /**
  * The application shell: a collapsible sidebar on wide viewports, a fixed bottom bar on narrow ones,
@@ -55,14 +56,14 @@ interface Props {
  * mobile form on a desktop, which is exactly what the showcase does.
  *
  * Entries come from `routing.children("/")`, minus plumbing (no `title`), minus any route with no page
- * of its own to link to, and minus anything the user context gates out. Home, when declared, is derived off the trail and rendered as the sidebar's
+ * of its own to link to (unless it heads a group), and minus anything the user context gates out. Home, when declared, is derived off the trail and rendered as the sidebar's
  * header entry and as the bottom bar's first item. It is current on the exact root and nowhere else —
  * every route is below it — while every other entry is current for its whole subtree, so exactly one
  * entry is ever marked, in either form.
  *
  * The bar form has no sidebar, and so no brand, no footer and no user block. All three move into the
  * sheet behind the "More" item, which is therefore shown whenever there is anything to put there —
- * overflowing entries, a `brand` snippet, a `footer` snippet or a signed-in user — and not only on an
+ * overflowing entries, a group's children, a `brand` snippet, a `footer` snippet or a signed-in user — and not only on an
  * overflow. The sheet reads brand, then the entries that did not fit, then `footer`, then the user
  * block with its sign-out control. Choosing an entry dismisses it; using a footer control does not.
  *

package/dist/shell/NavigationProgress.svelte

@@ -0,0 +1,85 @@
+<script lang="ts">
+  interface Props {
+    /** Whether a navigation is under way — `navigating.to !== null` from `$app/state`, typically. */
+    active: boolean;
+    /**
+     * How long a navigation has to take before the line shows, in milliseconds. Most client-side
+     * navigations finish well inside it, and a line that flashes for every one of them reads as
+     * flicker, not as progress.
+     */
+    delay?: number;
+  }
+
+  let { active, delay = 150 }: Props = $props();
+
+  let shown = $state(false);
+
+  $effect(() => {
+    if (!active) {
+      shown = false;
+      return;
+    }
+    const timer = setTimeout(() => (shown = true), delay);
+    return () => clearTimeout(timer);
+  });
+</script>
+
+<!--
+@component
+A thin line sweeping across the very top of the window while a navigation is taking a while — the
+only feedback a client-side navigation gives that something is happening between the click and the
+next page. It shows only once the navigation has taken longer than `delay`.
+
+The library imports nothing from SvelteKit, so the app says when a navigation is under way:
+
+```svelte
+<script>
+  import { navigating } from "$app/state";
+</script>
+
+<NavigationProgress active={navigating.to !== null} />
+```
+
+It is decoration — the page that is loading says so where it matters — so it stays hidden from
+assistive technology, and stops sweeping for a reader who asked for less motion.
+-->
+{#if shown}
+  <div class="plinth-navigation-progress" aria-hidden="true"><span></span></div>
+{/if}
+
+<style>
+  .plinth-navigation-progress {
+    position: fixed;
+    inset: 0 0 auto;
+    z-index: 60;
+    height: 2px;
+    overflow: hidden;
+    pointer-events: none;
+  }
+
+  .plinth-navigation-progress span {
+    display: block;
+    width: 40%;
+    height: 100%;
+    border-radius: 0 2px 2px 0;
+    background: linear-gradient(90deg, transparent, var(--color-primary));
+    animation: plinth-navigation-sweep 1.1s ease-in-out infinite;
+  }
+
+  @keyframes plinth-navigation-sweep {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(250%);
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .plinth-navigation-progress span {
+      width: 100%;
+      background: var(--color-primary);
+      animation: none;
+    }
+  }
+</style>

package/dist/shell/NavigationProgress.svelte.d.ts

@@ -0,0 +1,31 @@
+interface Props {
+    /** Whether a navigation is under way — `navigating.to !== null` from `$app/state`, typically. */
+    active: boolean;
+    /**
+     * How long a navigation has to take before the line shows, in milliseconds. Most client-side
+     * navigations finish well inside it, and a line that flashes for every one of them reads as
+     * flicker, not as progress.
+     */
+    delay?: number;
+}
+/**
+ * A thin line sweeping across the very top of the window while a navigation is taking a while — the
+ * only feedback a client-side navigation gives that something is happening between the click and the
+ * next page. It shows only once the navigation has taken longer than `delay`.
+ *
+ * The library imports nothing from SvelteKit, so the app says when a navigation is under way:
+ *
+ * ```svelte
+ * <script>
+ * import { navigating } from "$app/state";
+ * </script>
+ *
+ * <NavigationProgress active={navigating.to !== null} />
+ * ```
+ *
+ * It is decoration — the page that is loading says so where it matters — so it stays hidden from
+ * assistive technology, and stops sweeping for a reader who asked for less motion.
+ */
+declare const NavigationProgress: import("svelte").Component<Props, {}, "">;
+type NavigationProgress = ReturnType<typeof NavigationProgress>;
+export default NavigationProgress;