@publier/shell 3.6.1 → 4.0.0

package/README.md

@@ -1 +1,89 @@
 # @publier/shell
+
+## Navigation groups
+
+Both `nav.default.tabs` and `nav.default.links` accept plain links or one-level
+labelled groups. A group has `label` and `items`; its children have `label`, `href`,
+and optional `external` and `description`. Group labels open menus rather than
+navigate. Include an overview destination as a child when needed. Existing plain
+links keep their `label`, `href`, and optional `external` properties.
+
+```yaml
+nav:
+  default:
+    title: Example
+    tabs:
+      - label: Products
+        items:
+          - label: Overview
+            href: /products
+            description: Explore the products
+      - label: Solutions
+        items:
+          - label: Documentation sites
+            href: /solutions/documentation
+            description: Publish useful product guides
+      - label: Resources
+        items:
+          - label: Guides
+            href: /docs
+            description: Learn how to build your site
+          - label: Community
+            href: https://example.com/community
+            external: true
+    links:
+      - label: Sign in
+        href: /login
+    cta:
+      label: Talk to us
+      href: /contact
+```
+
+The default variant serves both marketing and documentation pages. Keep one
+canonical configuration; if named variants are needed, reuse the same YAML anchor
+instead of copying the items. Only one level is supported. Empty groups, malformed
+children, and nested groups are omitted. Descriptions are plain text and are
+escaped along with labels and destinations. Children support local paths,
+fragments, HTTP(S), mail and telephone links; executable URL schemes are omitted.
+`external: true` opens a new tab with `noopener noreferrer`.
+
+Desktop menus appear at `lg` (1024px). Each group is a native `<details>` with
+`data-publier-nav-group` set to its label. Its direct `<details-menu>` child has
+`data-publier-nav-menu`, `role="menu"`, and links with `role="menuitem"`. The
+existing lazy upgrade supplies menu keyboard navigation, Escape, and selection
+behavior. Native `name` attributes provide sibling exclusivity in supporting
+browsers. Descriptions use block spans with `whitespace-normal` and
+`data-publier-nav-description`.
+
+Below 1024px, the button named **Open navigation menu** has
+`data-publier-top-nav-toggle` and `aria-haspopup="dialog"`. It opens a labelled
+native dialog; the browser owns modal focus, focus restoration and Escape.
+The close button is named **Close navigation menu**. The menu container has
+`data-publier-nav-mobile`; each mobile group is also a `<details>` with the same
+group and menu attributes. Escape closes an open group first, then the containing
+dialog. Links and close buttons dismiss the dialog. Client-router navigation and
+crossing into the desktop layout clear open menus.
+
+The active destination uses `aria-current="page"`, chosen by longest local-path
+match. Group highlighting derives from that child. Grouped navigation rerenders
+on client-router transitions so desktop and mobile highlights reflect the new
+page. Search and theme slots continue to work; when composing `TopNav` directly,
+provide `TopNavMobile` in its `mobile` slot. `BaseLayout` supplies these navigation
+slots by default.
+
+## Migration from plain-link navigation types
+
+`NavLink.href` is now optional because a group uses `items` instead of a
+destination. Code that reads navigation entries must handle a group before
+using `href`; its child `NavItem` entries always have a destination. Existing
+plain-link YAML does not need to change.
+
+Mobile navigation uses the browser's native dialog rather than a custom focus
+trap. GitHub's [details-dialog element](https://github.com/github/details-dialog-element#deprecation-warning)
+is deprecated for accessibility concerns, and there is no maintained
+`@github/modal-dialog-element` package. The [native dialog standard](https://html.spec.whatwg.org/multipage/interactive-elements.html#the-dialog-element)
+provides focus containment, background inertness, and Escape dismissal.
+The small activation and navigation cleanup script leaves those semantics to
+the browser. Menu keyboard navigation remains owned by GitHub's details-menu
+element. That element does not dismiss on outside clicks; the navigation glue
+closes open groups when a click occurs outside them.

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { i as DocsShellOptions, m as docsShell } from "./integration-BHNGso70.mjs";
+import { h as docsShell, i as DocsShellOptions } from "./integration-BNKc2flb.mjs";
 import "astro/zod";
 //#region src/build/headers.d.ts
 /**

package/dist/{integration-BHNGso70.d.mts → integration-BNKc2flb.d.mts}

@@ -165,10 +165,18 @@ interface LlmsConfig {
   /** Restrict to these collections. Empty means every rendered collection. */
   collections: string[];
 }
-interface NavLink {
+interface NavItem {
   label: string;
   href: string;
   external?: boolean;
+  description?: string;
+}
+/** A plain link, or a labelled group of one-level navigation items. */
+interface NavLink {
+  label: string;
+  href?: string;
+  external?: boolean;
+  items?: NavItem[];
 }
 interface NavCta {
   label: string;
@@ -196,4 +204,4 @@ interface NavConfig {
 }
 declare function docsShell(options?: DocsShellOptions): AstroIntegration;
 //#endregion
-export { DocsSidebarMetaOverride as a, NavCta as c, NavVariant as d, SidebarAnchorConfig as f, publierCascadeHoistPlugin as g, hoistMediaOutOfUtilitiesLayer as h, DocsShellOptions as i, NavLink as l, docsShell as m, DocVersionConfig as n, LlmsConfig as o, SiteConfig as p, DocsConfig as r, NavConfig as s, AnnouncementConfig as t, NavPathRule as u };
+export { publierCascadeHoistPlugin as _, DocsSidebarMetaOverride as a, NavCta as c, NavPathRule as d, NavVariant as f, hoistMediaOutOfUtilitiesLayer as g, docsShell as h, DocsShellOptions as i, NavItem as l, SiteConfig as m, DocVersionConfig as n, LlmsConfig as o, SidebarAnchorConfig as p, DocsConfig as r, NavConfig as s, AnnouncementConfig as t, NavLink as u };

package/dist/integration.d.mts

@@ -1,2 +1,2 @@
-import { a as DocsSidebarMetaOverride, c as NavCta, d as NavVariant, f as SidebarAnchorConfig, g as publierCascadeHoistPlugin, h as hoistMediaOutOfUtilitiesLayer, i as DocsShellOptions, l as NavLink, m as docsShell, n as DocVersionConfig, o as LlmsConfig, p as SiteConfig, r as DocsConfig, s as NavConfig, t as AnnouncementConfig, u as NavPathRule } from "./integration-BHNGso70.mjs";
-export { AnnouncementConfig, DocVersionConfig, DocsConfig, DocsShellOptions, DocsSidebarMetaOverride, LlmsConfig, NavConfig, NavCta, NavLink, NavPathRule, NavVariant, SidebarAnchorConfig, SiteConfig, docsShell, hoistMediaOutOfUtilitiesLayer, publierCascadeHoistPlugin };
+import { _ as publierCascadeHoistPlugin, a as DocsSidebarMetaOverride, c as NavCta, d as NavPathRule, f as NavVariant, g as hoistMediaOutOfUtilitiesLayer, h as docsShell, i as DocsShellOptions, l as NavItem, m as SiteConfig, n as DocVersionConfig, o as LlmsConfig, p as SidebarAnchorConfig, r as DocsConfig, s as NavConfig, t as AnnouncementConfig, u as NavLink } from "./integration-BNKc2flb.mjs";
+export { AnnouncementConfig, DocVersionConfig, DocsConfig, DocsShellOptions, DocsSidebarMetaOverride, LlmsConfig, NavConfig, NavCta, NavItem, NavLink, NavPathRule, NavVariant, SidebarAnchorConfig, SiteConfig, docsShell, hoistMediaOutOfUtilitiesLayer, publierCascadeHoistPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@publier/shell",
-  "version": "3.6.1",
+  "version": "4.0.0",
   "license": "UNLICENSED",
   "description": "Qwik + Astro docs layout for Publier sites.",
   "type": "module",
@@ -115,7 +115,7 @@
     "@github/details-menu-element": "^1.0.13",
     "@github/relative-time-element": "^5.3.1",
     "@github/tab-container-element": "^4.9.0",
-    "@publier/native": "3.0.1",
+    "@publier/native": "4.0.0",
     "@tailwindcss/typography": "^0.5.20",
     "astro-pagefind": "^2.0.1",
     "daisyui": "^5.7.22",

package/src/styles/base.css

@@ -152,7 +152,13 @@ h6 {
  * rule simply doesn't apply to them, so their daisyUI-derived
  * foreground/background pair stays intact.
  */
-[data-publier-top-nav] a.btn-ghost[aria-current="page"] {
+/* Group state derives from the active child; descriptions retain normal
+ * foreground contrast. Mobile links use the same semantic active signal. */
+[data-publier-top-nav] a.btn-ghost[aria-current="page"],
+[data-publier-nav-menu] a[aria-current="page"],
+[data-publier-top-nav] details[data-publier-nav-group]:has(a[aria-current="page"]) > summary,
+[data-publier-nav-mobile] details[data-publier-nav-group]:has(a[aria-current="page"]) > summary,
+[data-publier-nav-dialog] a[aria-current="page"] {
 	color: var(--color-primary);
 	background-color: color-mix(in oklab, var(--color-primary) 12%, transparent);
 }

package/src/virtual-modules.d.ts

@@ -24,10 +24,19 @@ declare module 'virtual:publier-theme-css';
 declare module 'virtual:publier-custom-css';
 
 declare module 'virtual:publier-nav-config' {
-	export interface NavLink {
+	export interface NavItem {
 		label: string;
 		href: string;
 		external?: boolean;
+		description?: string;
+	}
+
+	/** A plain link, or a labelled group of one-level navigation items. */
+	export interface NavLink {
+		label: string;
+		href?: string;
+		external?: boolean;
+		items?: NavItem[];
 	}
 
 	export interface NavCta {