@helloimjolopez-pathway/pathway-components 0.9.0 → 0.10.0

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/avatar/avatar.jsx

@@ -0,0 +1,167 @@
+/**
+ * Avatar: a person's or a household's photo, initials or icon. Avatar Group:
+ * several people in one spot, up to three overlapping, then +N.
+ *
+ * Figma `Avatar`, set 68:659, and `Avatar Group`, set 9704:74872, page
+ * "↳ Avatar" (5926:18314). Spec: components/avatar/avatar-spec.md.
+ *
+ * Props mirror the Figma properties (CLAUDE.md §10 rule 9):
+ *   Size        size        XXXS 16, XXS 20, XS 24, S 32, M 40, L 56, XL 96.
+ *                           One pixel size per name for every content type.
+ *   Content     content     "Image" | "Text" | "Icon". Optional: when omitted
+ *                           it follows the data, src, else text, else icon.
+ *                           An Image whose photo fails to load falls back the
+ *                           same way (Radix Avatar's Fallback model).
+ *   Shape       shape       "Circle" for people, "Square" for households and
+ *                           things. Square radius grows with the size.
+ *   Style       avatarStyle "Fill" (brand tint) | "Stroke" (outline, dense
+ *                           lists). Image is Fill only.
+ *   Text        text        the initials, at most two letters.
+ *   Icon        icon        a Material Symbols Rounded ligature, FILL 1.
+ *                           "person", or "home" for a household.
+ *   Show Badge  showBadge   the ringed status dot. badgeStatus picks Positive
+ *                           (online) or Attention (away). Always say the
+ *                           status in words too; the dot is never announced.
+ *
+ * ACCESSIBILITY. Not interactive and never focusable. Pass `name` when the
+ * Avatar stands alone: it becomes role img with that name. When the name is
+ * shown beside it, leave `name` out and the Avatar is hidden from screen
+ * readers, so the name is not read twice.
+ */
+import React, { useEffect, useState } from "react";
+
+const C = (n) => `var(--semantic-color-${n})`;
+const U = (n) => `var(--semantic-layout-units-${n})`;
+const Y = (n) => `var(--semantic-type-${n})`;
+
+export const AVATAR_SIZES = ["XXXS", "XXS", "XS", "S", "M", "L", "XL"];
+export const AVATAR_CONTENTS = ["Image", "Text", "Icon"];
+export const AVATAR_SHAPES = ["Circle", "Square"];
+export const AVATAR_STYLES = ["Fill", "Stroke"];
+export const AVATAR_BADGE_STATUS = ["Positive", "Attention"];
+export const AVATAR_GROUP_SIZES = ["XS", "S", "M"];
+
+/** Per size: the box, initials type, square radius, icon and badge. Sizes are measurements, not tokens. */
+export const SIZES = {
+  XXXS: { px: 16, fontSize: Y("font-size-xxxs"), lineHeight: Y("line-height-xxxs-single"), radius: U("cornerradius-small"),  icon: 10, badge: 6 },
+  XXS:  { px: 20, fontSize: Y("font-size-xxxs"), lineHeight: Y("line-height-xxxs-single"), radius: U("cornerradius-small"),  icon: 12, badge: 7 },
+  XS:   { px: 24, fontSize: Y("font-size-xxs"),  lineHeight: Y("line-height-xxs-single"),  radius: U("cornerradius-small"),  icon: 14, badge: 8 },
+  S:    { px: 32, fontSize: Y("font-size-s"),    lineHeight: Y("line-height-s-single"),    radius: U("cornerradius-small"),  icon: 20, badge: 10 },
+  M:    { px: 40, fontSize: Y("font-size-r"),    lineHeight: Y("line-height-r-single"),    radius: U("cornerradius-base"),   icon: 24, badge: 12 },
+  L:    { px: 56, fontSize: Y("font-size-l"),    lineHeight: Y("line-height-l-single"),    radius: U("cornerradius-large"),  icon: 34, badge: 16 },
+  XL:   { px: 96, fontSize: Y("font-size-xxl"),  lineHeight: Y("line-height-xxl-single"),  radius: U("cornerradius-xlarge"), icon: 58, badge: 28 },
+};
+
+/** Colours and widths, all semantic tokens. */
+export const T = {
+  fill:         C("fill-static-brand-subtle"),           // Text and Icon, Style Fill
+  foreground:   C("foreground-static-brand-on-subtle"),  // initials and icon
+  imageFill:    C("fill-static-neutral-faint"),          // behind the photo
+  stroke:       C("stroke-static-neutral-base"),         // Style Stroke
+  strokeWidth:  U("borderwidth-thin"),
+  circle:       U("cornerradius-full"),
+  badgeRing:    C("stroke-static-neutral-mono"),
+  badgeRingW:   U("borderwidth-base"),
+  badge:        { Positive: C("fill-static-positive-strong"), Attention: C("fill-static-attention-strong") },
+  groupRing:    C("fill-surface-elevated"),              // Avatar Group, separates overlapping avatars
+  groupRingW:   U("borderwidth-thick"),
+  family:       Y("family-brand"),
+  weight:       Y("weight-semibold"),
+};
+
+/** First letters of the first and last name, at most two. */
+export function initialsFrom(name = "") {
+  const parts = String(name).trim().split(/\s+/).filter(Boolean);
+  if (!parts.length) return "";
+  const first = parts[0][0] || "";
+  const last = parts.length > 1 ? parts[parts.length - 1][0] : "";
+  return (first + last).toUpperCase();
+}
+
+export function Avatar({
+  size = "M",
+  content,
+  shape = "Circle",
+  avatarStyle = "Fill",
+  src,
+  text,
+  icon = "person",
+  name,
+  showBadge = false,
+  badgeStatus = "Positive",
+  style,
+  ...rest
+}) {
+  const z = SIZES[size] || SIZES.M;
+  const [failed, setFailed] = useState(false);
+  useEffect(() => setFailed(false), [src]);
+  const letters = (text || "").slice(0, 2);
+  const resolved = content === "Icon" ? "Icon"
+    : content === "Text" ? (letters ? "Text" : "Icon")
+    : src && !failed ? "Image"
+    : letters ? "Text" : "Icon";
+  const look = resolved === "Image" ? "Fill" : avatarStyle;
+  const radius = shape === "Square" ? z.radius : T.circle;
+  const root = {
+    position: "relative", flex: "none", boxSizing: "border-box",
+    display: "inline-flex", alignItems: "center", justifyContent: "center",
+    width: z.px, height: z.px, borderRadius: radius,
+    background: resolved === "Image" ? T.imageFill : look === "Stroke" ? "transparent" : T.fill,
+    boxShadow: look === "Stroke" ? `inset 0 0 0 ${T.strokeWidth} ${T.stroke}` : "none",
+    color: T.foreground, fontFamily: T.family, ...style,
+  };
+  const a11y = name ? { role: "img", "aria-label": name } : { "aria-hidden": true };
+  return (
+    <span data-pw-avatar="" data-size={size} data-content={resolved} style={root} {...a11y} {...rest}>
+      {resolved === "Image" && (
+        <img src={src} alt="" onError={() => setFailed(true)}
+          style={{ width: "100%", height: "100%", objectFit: "cover", display: "block", borderRadius: radius }} />
+      )}
+      {resolved === "Text" && (
+        <span aria-hidden="true" style={{ fontSize: z.fontSize, lineHeight: z.lineHeight, fontWeight: T.weight, letterSpacing: 0, whiteSpace: "nowrap" }}>{letters}</span>
+      )}
+      {resolved === "Icon" && (
+        <span className="material-symbols-rounded" aria-hidden="true"
+          style={{ fontSize: z.icon, width: z.icon, height: z.icon, fontVariationSettings: "'FILL' 1, 'wght' 400, 'GRAD' 0, 'opsz' 24",
+            lineHeight: 1 /* pathway-allow: the icon box is the glyph's em, sized by table 3.5 */ }}>{icon}</span>
+      )}
+      {showBadge && (
+        <span aria-hidden="true" data-pw-avatar-badge="" style={{
+          position: "absolute", right: 0, bottom: 0, boxSizing: "border-box", width: z.badge, height: z.badge,
+          borderRadius: T.circle, background: T.badge[badgeStatus] || T.badge.Positive,
+          boxShadow: `inset 0 0 0 ${T.badgeRingW} ${T.badgeRing}`,
+        }} />
+      )}
+    </span>
+  );
+}
+
+/**
+ * AvatarGroup: up to `max` avatars (3), overlapping by a quarter of their size,
+ * each ringed in the surface colour, then a +N count of the rest. One role img
+ * named with the people shown and how many more.
+ *
+ * Figma: Size (XS, S, M) maps to size; Show Avatar 3 and Show more follow from
+ * how many people there are and `showMore`.
+ */
+export function AvatarGroup({ people = [], size = "XS", max = 3, showMore = true, label, style, ...rest }) {
+  const z = SIZES[size] || SIZES.XS;
+  const shown = people.slice(0, max);
+  const more = people.length - shown.length;
+  const named = shown.map((p) => p.name).filter(Boolean);
+  const aria = label || (named.join(", ") + (more > 0 ? `, and ${more} more` : ""));
+  const ring = { boxShadow: `0 0 0 ${T.groupRingW} ${T.groupRing}` };
+  return (
+    <span data-pw-avatar-group="" role="img" aria-label={aria} style={{ display: "inline-flex", alignItems: "center", ...style }} {...rest}>
+      {shown.map((p, i) => (
+        <Avatar key={(p.name || "") + i} size={size} src={p.src} text={p.text || initialsFrom(p.name)} icon={p.icon}
+          style={{ ...ring, marginLeft: i ? -z.px / 4 : 0 }} />
+      ))}
+      {showMore && more > 0 && (
+        <Avatar size={size} content="Text" text={`+${more}`.slice(0, 3)} style={{ ...ring, marginLeft: shown.length ? -z.px / 4 : 0 }} />
+      )}
+    </span>
+  );
+}
+
+export default Avatar;