@helloimjolopez-pathway/pathway-components 0.9.0 → 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/package.json

@@ -1,7 +1,14 @@
 {
   "name": "@helloimjolopez-pathway/pathway-components",
-  "version": "0.9.0",
-  "description": "Pathway Design System React components",
+  "version": "0.9.1",
+  "description": "Pathway Design System components for Ministry Brands products: web components (pathway-nav-shell, pathway-top-nav, pathway-sidenav, pathway-accounting-sidenav and more) and React source.",
+  "homepage": "https://potential-bassoon-voz982n.pages.github.io/storybook/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ministry-brands-llc/jolopez-collab-pathwayds.git",
+    "directory": "component-package"
+  },
+  "license": "CC0-1.0",
   "type": "module",
   "sideEffects": [
     "./dist/*.js"