@helloimjolopez-pathway/pathway-components 0.8.1 → 0.9.1

package/README.md

@@ -0,0 +1,148 @@
+# Pathway Components
+
+The Pathway Design System's UI components, for Ministry Brands products. Each one ships two ways from this one package:
+
+- **Web components** (custom elements): one script tag, then plain HTML tags. Works in Blazor, Razor, Angular, Vue, React, jQuery or plain HTML.
+- **React source** (`.jsx`): for React apps that want the components as React components.
+
+The same components are on NuGet as [`Pathway.Components`](https://www.nuget.org/packages/Pathway.Components), at the same version.
+
+| | |
+|---|---|
+| Storybook (every component, live, with its tokens) | https://potential-bassoon-voz982n.pages.github.io/storybook/ (sign in with your Ministry Brands GitHub account) |
+| Source repo | https://github.com/ministry-brands-llc/jolopez-collab-pathwayds (visible to everyone in the Ministry Brands GitHub organisation) |
+| Developer guide, all stacks | [`docs/consuming-from-any-stack.md`](https://github.com/ministry-brands-llc/jolopez-collab-pathwayds/blob/main/docs/consuming-from-any-stack.md) |
+| Tokens package (required) | [`@helloimjolopez-pathway/pathway-tokens`](https://www.npmjs.com/package/@helloimjolopez-pathway/pathway-tokens) · NuGet [`Pathway.DesignTokens`](https://www.nuget.org/packages/Pathway.DesignTokens) |
+
+## What is in it
+
+| Component | Web component | React import (`@helloimjolopez-pathway/pathway-components/…`) |
+|---|---|---|
+| NavShell (TopNav + SideNav + page area) | `<pathway-nav-shell>` | `…/nav-shell` → `NavShell` |
+| TopNav | `<pathway-top-nav>` | `…/top-nav` → `TopNav` |
+| SideNav | `<pathway-sidenav>` | `…/sidenav` → `SideNav` |
+| Accounting side nav | `<pathway-accounting-sidenav>` | `…/accounting-side-nav` → `AccountingSideNav` |
+| Page Template | `<pathway-page-template>` | `…/page-template` → `PageTemplate` |
+| Button | `<pathway-button>` | `…/button` → `Button` |
+| Badge | `<pathway-badge>` | `…/badge` → `Badge` |
+| Tooltip | `<pathway-tooltip>` | `…/tooltip` → `Tooltip` |
+| Toggle Button | `<pathway-toggle-button>` | `…/toggle-button` → `ToggleButton` |
+| Radio | `<pathway-radio-group>` | `…/radio` → `RadioGroup` |
+| BottomSheet | `<pathway-bottom-sheet>` | `…/bottom-sheet` → `BottomSheet` |
+| Scroll-to-Enable | `<pathway-scroll-to-enable>` | `…/scroll-to-enable` → `ScrollToEnable` |
+| Dropdown | (React only) | `…/dropdown` → `Dropdown` |
+
+The web components are in three bundles under `dist/`:
+
+| File | Registers |
+|---|---|
+| `dist/pathway-components.js` | every tag above |
+| `dist/pathway-sidenav.js` | `<pathway-sidenav>` only |
+| `dist/pathway-accounting-sidenav.js` | `<pathway-accounting-sidenav>` only |
+
+Each bundle is self-contained: React is inside it, so the host page needs no React.
+
+## Set up a page (any stack)
+
+Three things go on the host page, once.
+
+```html
+<!-- 1. Tokens: every colour, size and font in the components is a CSS custom property from this file -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@helloimjolopez-pathway/pathway-tokens@12/dist/index.css">
+
+<!-- 2. Fonts -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Red+Hat+Text:wght@300;400;500;600;700&display=swap">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200">
+
+<!-- 3. The components -->
+<script type="module" src="https://cdn.jsdelivr.net/npm/@helloimjolopez-pathway/pathway-components@0.9/dist/pathway-components.js"></script>
+```
+
+Pin an exact version in production (`@0.9.1`, not `@0.9`).
+
+From npm instead of the CDN:
+
+```bash
+npm install @helloimjolopez-pathway/pathway-components @helloimjolopez-pathway/pathway-tokens
+```
+
+```js
+import "@helloimjolopez-pathway/pathway-tokens/css";
+import "@helloimjolopez-pathway/pathway-components/elements";   // registers every tag
+```
+
+From NuGet (.NET): the files are static web assets, so a Razor or Blazor page references them as
+
+```html
+<link rel="stylesheet" href="_content/Pathway.DesignTokens/index.css">
+<script type="module" src="_content/Pathway.Components/pathway-components.js"></script>
+```
+
+**Light and Dark, Amplify and NewCo.** Dark is `data-theme="dark"` on any element (it applies to everything inside). NewCo is `data-brand="newco"` plus the NewCo layer: `@helloimjolopez-pathway/pathway-tokens@12/dist/brands/newco/index.css` after the Amplify one.
+
+## The Accounting nav shell
+
+The whole Accounting frame (TopNav without search or actions, the Accounting side nav with the Financials mark and application switcher, and the page area) is one tag:
+
+```html
+<pathway-nav-shell app-switcher active-app-id="financials-home" active-nav-id="dashboard">
+  <main>Your page</main>
+</pathway-nav-shell>
+```
+
+Give it your real data as JavaScript properties, and listen for its events:
+
+```js
+const shell = document.querySelector("pathway-nav-shell");
+
+shell.org  = { id: "org-1", name: "Grace Community Church", campus: "Knoxville", initials: "GC" };
+shell.orgs = [ /* same shape, for the org switcher */ ];
+shell.user = { name: "Jo Lopez", initials: "JL", email: "jo@example.org" };
+// Optional: replace the built-in Accounting applications and their navs.
+// shell.appSwitcher = { label, icon, home: { id, label, navItems }, apps: [ { id, label, navItems } ] };
+
+shell.addEventListener("pathway-navigate",      (e) => router.go(e.detail.id));  // a nav item was chosen
+shell.addEventListener("pathway-app-select",    (e) => loadApp(e.detail.id));    // an application was chosen
+shell.addEventListener("pathway-org-select",    (e) => switchOrg(e.detail.id));
+shell.addEventListener("pathway-module-select", (e) => openModule(e.detail.id));
+```
+
+Attributes on `<pathway-nav-shell>`:
+
+| Attribute | What it does |
+|---|---|
+| `app-switcher` | Turns the side nav's application switcher on. With it on, TopNav hides search and actions unless you say otherwise |
+| `active-app-id` | The current application; updated when someone picks another |
+| `active-nav-id` | The current page in the side nav; updated on navigation |
+| `active-module-id` | The current module in TopNav (default `home`) |
+| `default-collapsed` | Start with the side nav as the 72 px rail on desktop |
+| `hide-search`, `hide-actions` | Hide TopNav's search, or its action icons |
+
+Other properties: `modules`, `navItems` or `navSections` (for a non-Accounting module). Slots: the unnamed slot is the page; `nav-header-end` and `nav-footer` add to the side nav.
+
+Only the side nav? Use `<pathway-accounting-sidenav active-app-id="financials-home">`, with the same `appSwitcher` property and the `pathway-app-select`, `pathway-navigate` and `pathway-collapse-change` events.
+
+## React
+
+```jsx
+import "@helloimjolopez-pathway/pathway-tokens/css";
+import { NavShell } from "@helloimjolopez-pathway/pathway-components/nav-shell";
+import { ACCOUNTING_APP_SWITCHER } from "@helloimjolopez-pathway/pathway-components/accounting-side-nav";
+
+<NavShell appSwitcher={ACCOUNTING_APP_SWITCHER} activeNavId="dashboard"
+  org={org} orgs={orgs} user={user}
+  onNavigate={(id) => go(id)} onOrgSelect={(id) => switchOrg(id)}>
+  <YourPage />
+</NavShell>
+```
+
+`ACCOUNTING_APP_SWITCHER` is the built-in Accounting data (applications and their navs); pass your own object of the same shape to change it.
+
+React and React DOM 17 or later are peer dependencies. The `.jsx` files are shipped as source, so your bundler compiles them (Vite, webpack with Babel, Next.js and esbuild all do by default).
+
+## Taking it into your product
+
+- **Depend on the package and pin the version.** You get fixes by bumping it, and nothing changes under you until you do. Every release is in the repo's history and on npm.
+- **What your review will find:** the web component bundles contain React, React DOM and `react-aria-components`; the components make no network calls and store nothing; the only external requests are the fonts above, which you can self-host. Licence: CC0-1.0.
+- **Accessibility is built in and should still be tested in your product:** keyboard focus rings, focus returning to triggers, Esc to close, 44 px touch targets, and hidden nav rows kept out of the tab order.
+- **Report a problem or ask for a change** in the repo, where the component's spec (`components/<name>/<name>-spec.md`) records how it is meant to behave.

package/components/nav-shell/nav-shell.jsx

@@ -13,7 +13,7 @@
 import React, { useState, useEffect, useCallback } from "react";
 import TopNav, { DEFAULT_MODULES } from "../top-nav/top-nav.jsx";
 import { SideNav } from "../sidenav/sidenav.jsx";
-import { ModuleMark } from "../module-icon/module-icon.jsx";
+import { moduleHeader } from "../sidenav/accounting-side-nav.jsx";
 
 // ─── CONSTANTS ────────────────────────────────────────────────────────────────
 const TOPNAV_H = 60; // px — spec §9.3 rule 1
@@ -292,7 +292,7 @@ export function NavShell({
           hideCollapseButton={isTablet || isMobile}
           headerEnd={navHeaderEnd}
           footer={navFooter}
-          headerStart={appSwitcher && appSwitcher.moduleMark ? <ModuleMark {...appSwitcher.moduleMark} /> : null}
+          headerStart={moduleHeader(appSwitcher)}
           appSwitcher={appSwitcher ? { ...appSwitcher, activeId: appActive, onSelect: handleAppSelect,
             // Mobile opens the menu as a BottomSheet (Figma 40016737:141824).
             presentation: isMobile ? "sheet" : "popover" } : null}

package/components/sidenav/accounting-side-nav.jsx

@@ -29,7 +29,8 @@
  */
 import React, { useEffect, useState } from "react";
 import { SideNav } from "./sidenav.jsx";
-import { ModuleMark } from "../module-icon/module-icon.jsx";
+import { SideNavHeaderLabel } from "./sidenav.jsx";
+import { ModuleIcon } from "../module-icon/module-icon.jsx";
 
 // The Accounting module's applications, each with its own side nav. NavShell's
 // `app-switcher` and <pathway-accounting-sidenav> fall back to this when no
@@ -49,7 +50,8 @@ const APP_NAV_STANDARD = ["Dashboard", "Enter", "Manage", "View", "Reports", "Mo
 export const ACCOUNTING_APP_SWITCHER = {
   label: "Financials Home",
   icon: "apps",
-  // The module's mark in the SideNav header (Figma Module.Mark, Accounting).
+  // The module's label in the SideNav header: Figma SideNav.Header.Label with
+  // the Accounting icon chip (40016737:141726, 2026-11-12).
   moduleMark: { module: "accounting", label: "Financials" },
   // The Accounting TopNav is TopNav.Global with Search and Actions hidden
   // (Figma 40007879:18072): module switcher, org switcher and profile only.
@@ -66,6 +68,15 @@ export const ACCOUNTING_APP_SWITCHER = {
     { id: "purchasing-management", label: "Purchasing Management", navItems: accountingNav("pm", ["Dashboard", "Enter", "Manage", "Reports", "Modify", "Help"]) },
   ],
 };
+// The nav header's start slot for a module: SideNav.Header.Label with the
+// module's icon chip. NavShell uses the same, so the two headers never differ.
+export function moduleHeader(appSwitcher) {
+  const m = appSwitcher && appSwitcher.moduleMark;
+  if (!m) return null;
+  return <SideNavHeaderLabel label={m.label}
+    icon={m.module ? <ModuleIcon module={m.module} size={14} color="mono" /> : null} />;
+}
+
 const MOBILE_MAX = 767; // below 768, as NavShell's breakpoint
 
 function useIsMobile() {
@@ -107,7 +118,7 @@ export function AccountingSideNav({
 
   return (
     <SideNav key={current && current.id} items={items} activeId={active} onNavigate={navigate}
-      headerStart={appSwitcher.moduleMark ? <ModuleMark {...appSwitcher.moduleMark} /> : null}
+      headerStart={moduleHeader(appSwitcher)}
       appSwitcher={{ ...appSwitcher, activeId: current && current.id, onSelect: selectApp, presentation: mode }}
       {...rest} />
   );

package/components/sidenav/sidenav.jsx

@@ -747,6 +747,38 @@ export function AppSwitcher({ label: fallbackLabel, icon = "apps", home, apps =
   );
 }
 
+// ─── SideNavHeaderLabel ───────────────────────────────────────────────────────
+// Figma SideNav.Header.Label (40018260:4928), read 2026-11-12 from the
+// Accounting Module Nav Shell (40016737:141726). The label at the start of the
+// nav header, beside the collapse control. Text only for a pillar rail; with
+// `icon`, the module's icon chip sits before the name (a module rail, such as
+// Accounting's Financials).
+//   IconChip  28, CornerRadius/Base, Fill/Static/Brand/Strong, clips
+//     icon    the module glyph at 14, Fill/Static/Neutral/Mono
+//   label     Heading/Local/Base/Semibold: 14 / 600 / 18 / 0.3,
+//             Foreground/Static/Neutral/Strong, truncates; gap Gap/XXTight
+//   width     160 in Figma: here it fills the row up to the collapse control
+export function SideNavHeaderLabel({ label, icon = null }) {
+  return (
+    <span style={{ display: "flex", alignItems: "center", minWidth: 0, flex: 1,
+      gap: "var(--semantic-layout-units-gap-xxtight)" }}>
+      {icon && (
+        <span aria-hidden="true" style={{ width: 28, height: 28, flexShrink: 0, overflow: "hidden",
+          display: "inline-flex", alignItems: "center", justifyContent: "center",
+          borderRadius: "var(--semantic-layout-units-cornerradius-base)",
+          background: c("fill-static-brand-strong"), color: c("fill-static-neutral-mono") }}>
+          {icon}
+        </span>
+      )}
+      <span style={{ flex: 1, minWidth: 0, fontFamily: "var(--semantic-type-family-brand)",
+        fontWeight: "var(--semantic-type-weight-semibold)", fontSize: "var(--semantic-type-font-size-s)",
+        lineHeight: "var(--semantic-type-line-height-s-tight)", letterSpacing: "var(--semantic-type-letter-spacing-spacious)",
+        color: c("foreground-static-neutral-strong"),
+        whiteSpace: "nowrap", overflow: "hidden", textOverflow: "ellipsis" }}>{label}</span>
+    </span>
+  );
+}
+
 // ─── CollapseButton ───────────────────────────────────────────────────────────
 // Redesigned in Figma (2026-05-12): now uses Slot.RowStart (Module.Mark icon)
 // + Slot.RowEnd (Action Icon). The action icon uses Foreground/Action/Secondary/Rest