@marktiderman/genesis-ui 2.11.0 → 2.12.1

package/SKILL.md

@@ -327,6 +327,63 @@ const navigation: NavigationNode<NavItem> = {
   linkComponent={RouterLink}>{children}</AppShell>
 ```
 
+**Collapsible sidebar.** On desktop the sidebar collapses to an icon rail (56px;
+`options.collapsedRailWidth: 64` for the wider one): the logo mark, one icon per item (name in a
+tooltip on hover and focus), nested groups in a popover, and the expand button at the bottom.
+The panel button beside the logo toggles it; `options.collapseShortcut: "["` adds an opt-in key
+(skipped while typing, in a listbox/combobox/menu, or with a dialog open). Pass
+`optionsStorageKey` (app-scoped, e.g. `"acme:app-shell"`) to remember the user's choice under
+`${key}:collapsed`. A page asks to open collapsed with `defaultCollapsed: true` on its
+`NavigationNode` (the nearest node in the trail that sets it wins) or `defaultCollapsed` on
+`AppShell`; the user's own toggle always wins once they have used it, and "Reset to defaults" in
+the sidebar options hands it back. `options.defaultCollapsed` is the app-wide default, and
+`collapsed` +
+`onCollapsedChange` make it controlled. The mobile drawer is unaffected.
+
+```tsx
+{ id: "builder", path: "/forms/$formId/edit", label: "Form builder", items: [], defaultCollapsed: true }
+```
+
+**Sub-navigation (a page's children).** A node's `items` are the current page's child items: a
+form's Questions / Logic and endings / Responses / Settings. A node's items are `NavItem`s,
+so each needs an `icon`. The hook (`useAppShellSubNav`) and the exported `SubNavTabs` take
+`SubNavItem`s instead: a `NavItem` whose `icon` is optional. Without one, the sidebar and mobile
+navigation show the label's first letter, and `SubNavTabs` shows the label alone. Each has `label`, `to` (a route, or a `?search` / `#hash`; active state follows the URL,
+most specific sibling wins) and an optional `badge` (a count or short status, shown as a chip). Gate by role the same way as other items: filter the list before handing
+it over.
+For live data (badge counts) the page calls `useAppShellSubNav(items, { mode? })`, which
+replaces the node's items while it is mounted, and puts a host chip at the end of the tab row with
+`<AppShellSubNavEnd>…</AppShellSubNavEnd>`. The page's resource header (breadcrumb, title,
+status, actions) goes in `<AppShellPageHeader>…</AppShellPageHeader>`, which the shell renders
+above the tab row (on phones too; at the top of the content when there is no row). Both are
+portals; when a layout and its page both mount one, the page's (innermost) renders, and the same
+rule picks between `useAppShellSubNav` callers. Shell sub-navigation is opt-in through
+`options.subNav`:
+
+- `"section"` (default): exactly the pre-sub-nav shell. The children sit in a labelled section
+  below the global sidebar items and replace the phone bar, with no back item.
+- `"tabs"`: one row of navigation links across the top of the content, badges as chips, the
+  current tab underlined in the brand colour, `aria-current="page"`.
+- `"sidebar"`: nested under the active global item ("Forms"); a flyout from it on the rail.
+- `"off"`: nothing, desktop or phone; draw your own (`SubNavTabs` is exported for that).
+
+With `"tabs"` or `"sidebar"`, a page with children swaps the phone bar to a back item to the
+logical parent ("Forms") plus the children and their badges; leaving the page brings the main
+bar back. A node (`subNav` on `NavigationNode`, nearest in the trail wins), the `subNav` prop and
+the page's hook override the option, in that order of strength (hook strongest), so one subtree
+can opt in. With it on, a page's children also win over an app-wide `mobileNavItems` on that page;
+in `"section"` / `"off"`, or on pages without children, `mobileNavItems` applies as before.
+
+```tsx
+useAppShellSubNav([
+  { to: `/forms/${id}/edit`, label: "Questions", icon: ListChecks, badge: questions.length, end: true },
+  { to: `/forms/${id}/edit/logic`, label: "Logic and endings", icon: GitBranch, badge: rules.length },
+  { to: `/forms/${id}/edit/responses`, label: "Responses", icon: Inbox, badge: responseCount },
+  { to: `/forms/${id}/edit/settings`, label: "Settings", icon: Settings },
+]);
+<AppShellSubNavEnd><Badge variant="success">Ready to publish</Badge></AppShellSubNavEnd>
+```
+
 For chrome outside AppShell, call the same resolver: `resolveNavigation(tree, pathname)` (from
 `/layout`, `/data` or the root barrel) returns `{ current, parent, items, trail, params }` with
 every path interpolated from the URL's params.

package/dist/AppShell-D5nD0mcL.d.ts

@@ -0,0 +1,348 @@
+import * as React from 'react';
+import { ReactNode } from 'react';
+import { LucideIcon } from 'lucide-react';
+import { L as LinkComponent } from './navigation-vmFJ6r1m.js';
+import { NavigationNode } from '@marktiderman/genesis-core/navigation';
+
+/**
+ * How AppShell shows the current page's child items. Sub-navigation is
+ * opt-in: the default, `section`, is the shell as it always was.
+ * - `section` (default): a labelled section below the global sidebar
+ *   items; on phones the children replace the bottom bar (no back item).
+ * - `tabs`: one row of tabs across the top of the page content.
+ * - `sidebar`: nested under the active item in the sidebar; a flyout from
+ *   that item on the collapsed rail.
+ * - `off`: nothing, on desktop or phones; the app draws its own
+ *   (`SubNavTabs` is exported for it).
+ *
+ * With `tabs` or `sidebar`, phones switch the bottom bar to a back item to
+ * the logical parent plus the children, with their badges.
+ *
+ * @stability Beta
+ */
+type SubNavMode = "section" | "tabs" | "sidebar" | "off";
+/**
+ * A sub-navigation item: a `NavItem` whose `icon` is optional (the tab row,
+ * the phone bar and the rail show the label's first letter without one).
+ * Every `NavItem` is a `SubNavItem`; `NavItem` itself keeps `icon` required.
+ *
+ * @stability Beta
+ */
+interface SubNavItem extends Omit<NavItem, "icon" | "children"> {
+    icon?: LucideIcon;
+    children?: SubNavItem[];
+}
+/**
+ * Props for {@link SubNavTabs}.
+ *
+ * @stability Beta
+ */
+interface SubNavTabsProps {
+    items: SubNavItem[];
+    /** Current location (`pathname + search + hash`); drives the active tab. */
+    activePath?: string;
+    linkComponent: LinkComponent;
+    isActive?: (to: string, activePath?: string) => boolean;
+    /** Right-aligned slot in the row, e.g. a "Ready to publish" chip. */
+    end?: ReactNode;
+    /** Accessible name of the `<nav>` (default "Page sections"). */
+    label?: string;
+    className?: string;
+}
+/**
+ * A row of navigation tabs: real links (deep links and middle-click work),
+ * `aria-current="page"` on the active one, badges as chips, the active tab
+ * underlined in the brand colour. AppShell renders it in `tabs` mode; an app
+ * using `subNav: "off"` can place it itself.
+ *
+ * @stability Beta
+ */
+declare function SubNavTabs({ items, activePath, linkComponent: LinkComp, isActive, end, label, className, }: SubNavTabsProps): React.JSX.Element;
+/**
+ * Options for {@link useAppShellSubNav}.
+ *
+ * @stability Beta
+ */
+interface UseAppShellSubNavOptions {
+    /** This page's `subNav` mode; wins over the shell's and the node's. */
+    mode?: SubNavMode;
+}
+/**
+ * Give the shell this page's child items (sub-navigation) while the page is
+ * mounted. They replace the current `NavigationNode`'s `items`; pass
+ * `null` / `undefined` to fall back to them (a `mode` still applies). When
+ * several components call it (a layout and its page), the innermost wins,
+ * for items and for mode separately. Use it when children depend on
+ * page data, such as live badge counts. A fresh array each render is fine:
+ * the shell only updates when a `to`, label, badge, icon or flag changes.
+ *
+ * ```tsx
+ * useAppShellSubNav([
+ *   { to: `/forms/${id}/edit`, label: "Questions", icon: ListChecks, badge: questions.length, end: true },
+ *   { to: `/forms/${id}/edit/logic`, label: "Logic and endings", icon: GitBranch, badge: rules.length },
+ *   { to: `/forms/${id}/edit/responses`, label: "Responses", icon: Inbox, badge: responses },
+ *   { to: `/forms/${id}/edit/settings`, label: "Settings", icon: Settings },
+ * ]);
+ * ```
+ *
+ * Does nothing outside an `AppShell`.
+ *
+ * @stability Beta
+ */
+declare function useAppShellSubNav(items: SubNavItem[] | null | undefined, options?: UseAppShellSubNavOptions): void;
+/**
+ * Render `children` in the right-hand slot of the shell's sub-navigation
+ * tab row, e.g. a "Ready to publish" status chip. Rendered through a
+ * portal, so it keeps the page's context and state. Renders nothing when
+ * the shell shows no tab row (other modes, phones, no children). When
+ * several are mounted (a layout's and a page's), the innermost renders.
+ *
+ * @stability Beta
+ */
+declare function AppShellSubNavEnd({ children }: {
+    children: ReactNode;
+}): ReactNode;
+/**
+ * Render the page's resource header (breadcrumb, title, status, actions) at
+ * the top of the shell's content, ABOVE the sub-navigation tab row, where
+ * the design puts it. A portal like `AppShellSubNavEnd`, so it keeps the
+ * page's state; the innermost mounted one renders. On phones it stays at
+ * the top of the content while the bottom bar carries the children. With
+ * no tab row (the default `"section"` mode, or a page without children) it
+ * simply sits at the top of the content. Mount none and the layout is
+ * unchanged.
+ *
+ * @stability Beta
+ */
+declare function AppShellPageHeader({ children }: {
+    children: ReactNode;
+}): ReactNode;
+
+interface NavItem {
+    /** Route, optionally with `?search` / `#hash` (see `isPathActive`). */
+    to: string;
+    icon: LucideIcon;
+    label: string;
+    /** Nested items — rendered as a collapsible group when the rail is expanded */
+    children?: NavItem[];
+    /**
+     * A count (`3`) or a short status (`"New"`), shown as a chip: in the
+     * sidebar, the sub-navigation tabs and the mobile bar; as a dot on the
+     * collapsed rail. It is part of the item's accessible name where the label
+     * is hidden.
+     */
+    badge?: string | number;
+    disabled?: boolean;
+    /**
+     * Exact-match active state (e.g. overview `/`). Exact on the path only, so
+     * an `activePath` carrying `?search#hash` still matches.
+     */
+    end?: boolean;
+}
+/**
+ * The "up" link AppShell renders above page content: a real link to the
+ * logical parent, never `history.back()`.
+ *
+ * @stability Beta
+ */
+interface ParentNavigation {
+    href: string;
+    label: string;
+}
+/**
+ * Declarative chrome for AppShell — developer defaults + optional
+ * in-sidebar user toggles (Notion/Linear “customize chrome” pattern).
+ *
+ * @stability Beta
+ */
+interface AppShellOptions {
+    showLogo?: boolean;
+    showAppName?: boolean;
+    showThemeToggle?: boolean;
+    /** Desktop rail collapse control */
+    showCollapse?: boolean;
+    showUserSlot?: boolean;
+    showFooter?: boolean;
+    showSecondaryNav?: boolean;
+    /** Mobile fixed bottom tab bar */
+    showMobileBottomNav?: boolean;
+    /**
+     * Open the desktop sidebar collapsed (an icon rail, `collapsedRailWidth` wide) when the user hasn't
+     * chosen. The app-wide default; a page asks for its own through
+     * `AppShellProps.defaultCollapsed` or `NavigationNode.defaultCollapsed`.
+     */
+    defaultCollapsed?: boolean;
+    /**
+     * Opt-in key that toggles the desktop sidebar, e.g. `"["` as in Linear and
+     * Notion. Off (`false`) by default. It never fires while typing in a field,
+     * while a listbox, combobox or menu has focus (Select typeahead), while a
+     * dialog is open, with Ctrl/Cmd/Alt held, or when `showCollapse` is off.
+     */
+    collapseShortcut?: string | false;
+    /**
+     * Width of the collapsed icon rail in px: `56` (default, as before) or
+     * `64` (the Breakthrough design).
+     */
+    collapsedRailWidth?: 56 | 64;
+    /**
+     * Shell sub-navigation, opt-in. `"section"` (default) renders a page's
+     * children exactly as AppShell always has; `"tabs"` or `"sidebar"` turn
+     * sub-navigation on (see `SubNavMode`), and `"off"` hides them. A
+     * navigation node, the `subNav` prop or the page
+     * (`useAppShellSubNav(items, { mode })`) can override it.
+     */
+    subNav?: SubNavMode;
+    /**
+     * Show the in-sidebar Sidebar options popover so users can customize chrome.
+     * Default true when collapse / secondary / theme / slots are available.
+     */
+    configurable?: boolean;
+    /**
+     * Toggle keys the developer has decided on and users may not override —
+     * e.g. hiding `showThemeToggle` for a brand that manages theme elsewhere.
+     * Locked keys are dropped from the options popover and any stored user
+     * override for them is ignored on resolve.
+     */
+    lockedOptions?: (keyof AppShellOptions)[];
+    /** Comfortable (default) vs compact row padding */
+    density?: "comfortable" | "compact";
+    /** Expanded rail width in rem-ish tokens: narrow ≈ 13rem, wide ≈ 16rem */
+    railWidth?: "narrow" | "wide";
+    /**
+     * Where page content scrolls.
+     * - `container` (default): main panel scrolls — classic app-shell chrome.
+     * - `window`: document/window scrolls with a sticky rail so React Router
+     *   `ScrollRestoration` keeps working (dashboard dogfood).
+     */
+    scrollRoot?: "container" | "window";
+}
+/**
+ * @stability Beta
+ */
+interface AppShellProps {
+    /** App name shown in sidebar header */
+    appName: string;
+    /** App logo letter or short text (ignored when `logo` is set) */
+    appLogo?: string;
+    /** Custom logo node — preferred over `appLogo` letter tile */
+    logo?: ReactNode;
+    /**
+     * Primary navigation items. Optional when `navigation` is set: the tree
+     * root's `items` are the global nav then.
+     */
+    navItems?: NavItem[];
+    /**
+     * The app's logical navigation hierarchy. AppShell resolves it against
+     * `activePath` (see `resolveNavigation`) and derives:
+     * - the sidebar's global items from the root's `items` (unless `navItems`),
+     * - a contextual section from the current node's `items`, labelled with
+     *   the node's `label` (`$param` segments in `to` filled from the URL),
+     * - the mobile tab bar: the contextual items when there are any, else the
+     *   global top-level items (unless `mobileNavItems`),
+     * - a back link to the current node's logical parent (unless
+     *   `parentNavigation`).
+     *
+     * @stability Beta
+     */
+    navigation?: NavigationNode<NavItem>;
+    /**
+     * Back-to-parent link rendered in the content header, above `children`, on
+     * mobile and desktop. Derived from `navigation` when omitted; `null` hides
+     * it. Use this instead of placing a back row inside page content.
+     *
+     * @stability Beta
+     */
+    parentNavigation?: ParentNavigation | null;
+    /** Secondary nav (e.g. “More”) — rendered below a divider when shown */
+    secondaryNavItems?: NavItem[];
+    /** Label above secondary nav (default “More”) */
+    secondaryNavLabel?: string;
+    /**
+     * Items for the mobile bottom tab bar. Defaults to top-level `navItems`
+     * (no children). Pass a short list for apps with large sidebars; pass `[]`
+     * and set `options.showMobileBottomNav: false` to hide.
+     */
+    mobileNavItems?: NavItem[];
+    /** Slot below the logo row (product switcher, workspace picker, …) */
+    headerSlot?: ReactNode;
+    /**
+     * Compact slot shown in the **collapsed** desktop rail, where `headerSlot`
+     * is hidden for space. Use it to keep a core affordance reachable without
+     * expanding — e.g. an icon-only product switcher. Omit to hide the header
+     * region entirely while collapsed.
+     */
+    collapsedHeaderSlot?: ReactNode;
+    /** Footer region above the user slot (version, links) */
+    footer?: ReactNode;
+    /**
+     * User / account block at the bottom of the sidebar. When the rail is
+     * collapsed, AppShell hides any descendant carrying the
+     * `data-shell-user-detail` attribute (e.g. name/email text) so only a
+     * compact element (avatar, initial) remains — tag the detail wrapper you
+     * want hidden in the collapsed rail with that attribute.
+     */
+    userSlot?: ReactNode;
+    /** Page content */
+    children: ReactNode;
+    /**
+     * @deprecated Prefer `options.showThemeToggle`. Kept for sample-app
+     * back-compat; merges into resolved options when `options` omits it.
+     */
+    showThemeToggle?: boolean;
+    /** Chrome config (developer defaults + optional in-sidebar menu) */
+    options?: AppShellOptions;
+    /** Persist user sidebar-option overrides + collapse state (localStorage) */
+    optionsStorageKey?: string;
+    /**
+     * Controlled collapse (desktop rail). Overrides the stored user choice and
+     * every default.
+     */
+    collapsed?: boolean;
+    /** Called with the new state whenever the user toggles the sidebar. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * This page's default: open the desktop sidebar collapsed (`true`) or
+     * expanded (`false`) until the user toggles it. Reactive, so a layout can
+     * pass it per route. Wins over `navigation`'s `defaultCollapsed` and
+     * `options.defaultCollapsed`; the user's own choice (persisted under
+     * `optionsStorageKey`) wins over all of them.
+     *
+     * @stability Beta
+     */
+    defaultCollapsed?: boolean;
+    /**
+     * This page's sub-navigation mode (see `AppShellOptions.subNav`). Wins
+     * over `navigation`'s `subNav` and `options.subNav`; the page's own
+     * `useAppShellSubNav(items, { mode })` wins over it.
+     *
+     * @stability Beta
+     */
+    subNav?: SubNavMode;
+    /**
+     * Accessible name of the sub-navigation tab row. Defaults to the current
+     * navigation node's label, else "Page sections".
+     */
+    subNavLabel?: string;
+    /**
+     * Injectable link component. Defaults to a plain `<a>` (no router). Pass a
+     * router adapter — e.g. React Router `({ href, ...p }) => <Link to={href} {...p} />`
+     * or Next.js `next/link` — to get client-side navigation.
+     */
+    linkComponent?: LinkComponent;
+    /**
+     * Current location used to highlight the active nav item. Pass the full
+     * location, `pathname + search + hash` (React Router: `useLocation()`), so
+     * items whose `to` names a query or hash (`/admin?tab=users`) can become
+     * active. A pathname alone still works for path-only items, `end` included.
+     * Omit to disable active highlighting.
+     */
+    activePath?: string;
+    /**
+     * Optional custom active-state matcher. Defaults to a prefix match (with `/`
+     * treated as exact), mirroring React Router `NavLink`.
+     */
+    isActive?: (to: string, activePath?: string) => boolean;
+}
+declare function AppShell({ appName, appLogo, logo, navItems: navItemsProp, navigation, parentNavigation: parentNavigationProp, secondaryNavItems, secondaryNavLabel, mobileNavItems, headerSlot, collapsedHeaderSlot, footer, userSlot, children, showThemeToggle: showThemeToggleProp, options: optionsProp, optionsStorageKey, collapsed: collapsedProp, onCollapsedChange, defaultCollapsed: defaultCollapsedProp, subNav: subNavProp, subNavLabel, linkComponent, activePath, isActive, }: AppShellProps): React.JSX.Element;
+
+export { AppShell as A, type NavItem as N, type ParentNavigation as P, type SubNavItem as S, type UseAppShellSubNavOptions as U, type AppShellOptions as a, AppShellPageHeader as b, type AppShellProps as c, AppShellSubNavEnd as d, type SubNavMode as e, SubNavTabs as f, type SubNavTabsProps as g, useAppShellSubNav as u };

package/dist/chunk-424PT5DM.js

@@ -0,0 +1,21 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+
+export { __export, __reExport };
+//# sourceMappingURL=chunk-424PT5DM.js.map
+//# sourceMappingURL=chunk-424PT5DM.js.map

package/dist/chunk-424PT5DM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"chunk-424PT5DM.js"}