@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/breadcrumb/passport.json

@@ -0,0 +1,243 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Breadcrumb",
+    "folder": "breadcrumb",
+    "exports": [
+      "Breadcrumb"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/trail.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Breadcrumb.tsx",
+      "react/locale.ts",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:f3093ad51f16f3bae86b349a012218e71848f7c7d624d27d41ac578bb55da82c"
+  },
+  "props": [
+    {
+      "name": "aria-describedby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "aria-labelledby",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<BreadcrumbSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "items",
+      "type": "other",
+      "typeText": "readonly BreadcrumbItem[]",
+      "required": true,
+      "origin": "derived",
+      "description": "From the top level to the current page. The last item is the current page.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "itemsAfterCollapse",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 1,
+      "origin": "derived",
+      "description": "Crumbs kept after the collapsed part. Default 1.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "itemsBeforeCollapse",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 1,
+      "origin": "derived",
+      "description": "Crumbs kept before the collapsed part. Default 1.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "localeText",
+      "type": "other",
+      "typeText": "Partial<BreadcrumbLocaleText> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "maxItems",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Collapse the middle of the trail when it has more crumbs than this.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "renderLink",
+      "type": "function",
+      "signature": "((props: BreadcrumbLinkProps) => ReactElement) | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Draw links with your router, e.g. `(props) => <Link {...props} />`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "separator",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Between crumbs. Default a chevron.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "'sm' | 'md' | 'lg' | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived"
+    },
+    {
+      "name": "structuredData",
+      "type": "other",
+      "typeText": "boolean | { baseUrl: string; } | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Add schema.org `BreadcrumbList` JSON-LD for search engines. Pass\n`{ baseUrl }` so relative links become absolute, as search engines require.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLElement>",
+      "omitted": [
+        "children"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [],
+  "slots": [
+    "item",
+    "ellipsis",
+    "root",
+    "list",
+    "link",
+    "current",
+    "separator"
+  ],
+  "states": [
+    {
+      "attr": "data-index"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 20,
+    "propsDescribed": 7,
+    "describedPct": 35,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/breadcrumb/react/Breadcrumb.tsx

@@ -0,0 +1,177 @@
+"use client";
+
+import {
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+import { collapseItems, toBreadcrumbJsonLd } from "../core/trail";
+import type { BreadcrumbItem, BreadcrumbLocaleText } from "../core/types";
+import { defaultBreadcrumbText } from "./locale";
+import { cx, type BreadcrumbLinkProps, type BreadcrumbSlot } from "./props";
+
+export interface BreadcrumbProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /** From the top level to the current page. The last item is the current page. */
+  items: readonly BreadcrumbItem[];
+  /** Between crumbs. Default a chevron. */
+  separator?: ReactNode;
+  /** Collapse the middle of the trail when it has more crumbs than this. */
+  maxItems?: number;
+  /** Crumbs kept before the collapsed part. Default 1. */
+  itemsBeforeCollapse?: number;
+  /** Crumbs kept after the collapsed part. Default 1. */
+  itemsAfterCollapse?: number;
+  /** Draw links with your router, e.g. `(props) => <Link {...props} />`. */
+  renderLink?(props: BreadcrumbLinkProps): ReactElement;
+  /**
+   * Add schema.org `BreadcrumbList` JSON-LD for search engines. Pass
+   * `{ baseUrl }` so relative links become absolute, as search engines require.
+   */
+  structuredData?: boolean | { baseUrl: string };
+  size?: "sm" | "md" | "lg";
+  classNames?: Partial<Record<BreadcrumbSlot, string>>;
+  localeText?: Partial<BreadcrumbLocaleText>;
+}
+
+const Chevron = () => (
+  <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" focusable="false">
+    <path d="m9 18 6-6-6-6" />
+  </svg>
+);
+
+/** Where the current page sits in the site's hierarchy. */
+export function Breadcrumb(props: BreadcrumbProps) {
+  const {
+    items,
+    separator,
+    maxItems,
+    itemsBeforeCollapse = 1,
+    itemsAfterCollapse = 1,
+    renderLink,
+    structuredData = false,
+    size = "md",
+    className,
+    classNames,
+    localeText,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultBreadcrumbText, ...localeText }), [localeText]);
+  const listRef = useRef<HTMLOListElement>(null);
+  const [expanded, setExpanded] = useState(false);
+  const [revealFrom, setRevealFrom] = useState<number | null>(null);
+
+  // After expanding, move focus to the first crumb that was hidden, not to <body>.
+  useEffect(() => {
+    if (revealFrom === null) return;
+    listRef.current?.querySelector<HTMLElement>(`[data-index="${revealFrom}"] :is(a, button, [tabindex])`)?.focus();
+  }, [revealFrom]);
+
+  const slots = expanded
+    ? collapseItems(items.length)
+    : collapseItems(items.length, maxItems, itemsBeforeCollapse, itemsAfterCollapse);
+  const lastIndex = items.length - 1;
+
+  const renderItem = (item: BreadcrumbItem, index: number) => {
+    const content = (
+      <>
+        {item.icon && (
+          <span className="bc-icon" aria-hidden="true">
+            {item.icon}
+          </span>
+        )}
+        <span className="bc-text" title={typeof item.label === "string" ? item.label : undefined}>
+          {item.label}
+        </span>
+      </>
+    );
+
+    if (index === lastIndex || (!item.href && !item.onClick)) {
+      return (
+        <span
+          className={cx("bc-current", classNames?.current)}
+          aria-current={index === lastIndex ? "page" : undefined}
+        >
+          {content}
+        </span>
+      );
+    }
+    if (item.href) {
+      const linkProps: BreadcrumbLinkProps = {
+        href: item.href,
+        className: cx("bc-link", classNames?.link),
+        children: content,
+        onClick: item.onClick ? () => item.onClick?.() : undefined,
+      };
+      return renderLink ? renderLink(linkProps) : <a {...linkProps} />;
+    }
+    return (
+      <button type="button" className={cx("bc-link", classNames?.link)} onClick={item.onClick}>
+        {content}
+      </button>
+    );
+  };
+
+  const jsonLd = structuredData
+    ? toBreadcrumbJsonLd(
+        items.map((item) => ({
+          name: item.name ?? (typeof item.label === "string" ? item.label : ""),
+          href: item.href,
+        })),
+        typeof structuredData === "object" ? structuredData.baseUrl : undefined,
+      )
+    : null;
+
+  return (
+    <nav
+      {...rest}
+      aria-label={ariaLabel ?? text.label}
+      className={cx("bc-root", classNames?.root, className)}
+      data-size={size}
+    >
+      <ol ref={listRef} className={cx("bc-list", classNames?.list)}>
+        {slots.map((slot, position) => (
+          <li
+            key={slot.kind === "item" ? slot.index : "ellipsis"}
+            className={cx("bc-item", classNames?.item)}
+            data-index={slot.kind === "item" ? slot.index : undefined}
+          >
+            {position > 0 && (
+              <span className={cx("bc-separator", classNames?.separator)} aria-hidden="true">
+                {separator ?? <Chevron />}
+              </span>
+            )}
+            {slot.kind === "item" ? (
+              renderItem(items[slot.index], slot.index)
+            ) : (
+              <button
+                type="button"
+                className={cx("bc-ellipsis", classNames?.ellipsis)}
+                aria-label={text.showMore(String(slot.hidden.length))}
+                title={text.showMore(String(slot.hidden.length))}
+                onClick={() => {
+                  setExpanded(true);
+                  setRevealFrom(slot.hidden[0]);
+                }}
+              >
+                …
+              </button>
+            )}
+          </li>
+        ))}
+      </ol>
+      {jsonLd && (
+        <script
+          type="application/ld+json"
+          // `<` is escaped so a crumb's name can never close the script tag.
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd).replace(/</g, "\\u003c") }}
+        />
+      )}
+    </nav>
+  );
+}

package/source/components/breadcrumb/react/locale.ts

@@ -0,0 +1,6 @@
+import type { BreadcrumbLocaleText } from "../core/types";
+
+export const defaultBreadcrumbText: BreadcrumbLocaleText = {
+  label: "Breadcrumb",
+  showMore: (count) => `Show ${count} more`,
+};

package/source/components/breadcrumb/react/props.ts

@@ -0,0 +1,14 @@
+import type { MouseEventHandler, ReactNode } from "react";
+
+export type BreadcrumbSlot = "root" | "list" | "item" | "link" | "current" | "separator" | "ellipsis";
+
+/** Handed to `renderLink`, to draw a crumb with your router's link component. */
+export interface BreadcrumbLinkProps {
+  href: string;
+  className: string;
+  children: ReactNode;
+  onClick?: MouseEventHandler<HTMLAnchorElement>;
+}
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/breadcrumb/styles.css

@@ -0,0 +1,138 @@
+/*
+ * Breadcrumb styles.
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (set them on :root to theme every component at once) and fall back to the
+ * same default palette otherwise. Rules are unlayered: they beat a framework
+ * reset on specificity, and lose to anything you pass through `className`.
+ * With Tailwind v4, import this file after the framework and inside its
+ * components layer - see the README.
+ */
+
+.bc-root {
+  --bc-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --bc-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --bc-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --bc-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --bc-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  /* Long labels are cut with an ellipsis; the full text is in the tooltip. */
+  --bc-max-label: 24ch;
+
+  color-scheme: inherit;
+  font-size: var(--bc-font-size);
+  line-height: 1.4;
+  color: var(--bc-muted);
+}
+
+:where(.dark, [data-theme="dark"]) .bc-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .bc-root {
+  color-scheme: light;
+}
+
+:where(.bc-root) *,
+:where(.bc-root) *::before,
+:where(.bc-root) *::after {
+  box-sizing: border-box;
+}
+
+.bc-root[data-size="sm"] {
+  --bc-font-size: 12px;
+}
+.bc-root[data-size="lg"] {
+  --bc-font-size: 14px;
+}
+
+.bc-list {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 4px 6px;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+.bc-item {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.bc-link,
+.bc-current {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  min-width: 0;
+}
+.bc-link {
+  margin: -2px -4px;
+  padding: 2px 4px;
+  border: 0;
+  border-radius: 4px;
+  background: none;
+  color: inherit;
+  font: inherit;
+  text-decoration: none;
+  cursor: pointer;
+}
+.bc-link:hover {
+  color: var(--bc-fg);
+  text-decoration: underline;
+  text-underline-offset: 3px;
+}
+.bc-link:focus-visible,
+.bc-ellipsis:focus-visible {
+  outline: 2px solid var(--bc-focus);
+  outline-offset: 1px;
+}
+.bc-current {
+  color: var(--bc-fg);
+  font-weight: 500;
+}
+
+.bc-text {
+  max-width: var(--bc-max-label);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.bc-icon {
+  display: inline-flex;
+  flex: none;
+}
+.bc-icon > svg {
+  width: 1.1em;
+  height: 1.1em;
+}
+
+.bc-separator {
+  display: inline-flex;
+  flex: none;
+  opacity: 0.7;
+}
+/* A chevron points the reading direction. */
+.bc-separator > svg:dir(rtl) {
+  transform: scaleX(-1);
+}
+
+.bc-ellipsis {
+  display: inline-grid;
+  place-items: center;
+  min-width: 24px;
+  height: 22px;
+  padding: 0 4px;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  letter-spacing: 1px;
+  cursor: pointer;
+}
+.bc-ellipsis:hover {
+  background: var(--bc-hover);
+  color: var(--bc-fg);
+}

package/source/components/button/README.md

@@ -0,0 +1,32 @@
+# Button
+
+A button for React 19 with variants, sizes, icons and a loading state that
+manages itself, styled to match the rest of the library. No runtime
+dependencies besides React.
+
+```ts
+import { Button } from "@/components/button";
+import "@/components/button/styles.css";
+```
+
+```tsx
+<Button onClick={async () => await save()}>Save</Button>          {/* spinner while the promise runs */}
+<Button type="submit">Create</Button>                            {/* spinner while the form's Server Action runs */}
+<Button variant="outline" leading={<PlusIcon />}>New invoice</Button>
+<Button variant="ghost" icon={<TrashIcon />} aria-label="Delete" />
+<Button render={(props) => <Link href="/billing" {...props} />}>Billing</Button>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `variant` | `primary` | `primary`, `secondary`, `outline`, `ghost`, `danger`, `link`. |
+| `size` | `md` | `sm` 30 · `md` 36 · `lg` 44 px. |
+| `type` | `button` | Not `submit`, so buttons inside forms don't submit by accident. |
+| `loading` / `loadingText` | `false` / — | Busy state; stays focusable and keeps its width. |
+| `leading`, `trailing`, `icon` | — | Icons; `icon` alone makes an icon-only button (add `aria-label`). |
+| `fullWidth` | `false` | Fill the container. |
+| `onClick` | — | Return a promise to show loading until it settles. |
+| `render` | — | Render another element (e.g. a router link) with the button's look. |
+| `className`, `classNames`, `localeText`, `ref` | — | Slots: `root`, `content`, `spinner`, `icon`. |
+
+Every other `<button>` attribute passes through.

package/source/components/button/core/index.ts

@@ -0,0 +1,3 @@
+// Framework-free: the button's state rules.
+export { buttonState, isPromiseLike } from "./state";
+export type * from "./types";

package/source/components/button/core/state.ts

@@ -0,0 +1,16 @@
+import type { ButtonState, ButtonStateInput } from "./types";
+
+/** An async click handler's return value: anything with a `then`. */
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === "function"
+  );
+}
+
+/** How a button behaves for its combination of flags. */
+export function buttonState({ disabled = false, loading = false, pending = false }: ButtonStateInput): ButtonState {
+  const busy = !disabled && (loading || pending);
+  return { busy, inactive: disabled || busy, nativeDisabled: disabled };
+}

package/source/components/button/core/types.ts

@@ -0,0 +1,28 @@
+export type ButtonVariant = "primary" | "secondary" | "outline" | "ghost" | "danger" | "link";
+
+export type ButtonSize = "sm" | "md" | "lg";
+
+export interface ButtonStateInput {
+  disabled?: boolean;
+  /** Set by you. */
+  loading?: boolean;
+  /** Set by the button itself: an async `onClick` or a pending form action. */
+  pending?: boolean;
+}
+
+export interface ButtonState {
+  /** Show the spinner and `aria-busy`. */
+  busy: boolean;
+  /** Ignore activation. */
+  inactive: boolean;
+  /**
+   * Use the native `disabled` attribute. A busy button stays focusable and uses
+   * `aria-disabled` instead, so keyboard focus isn't thrown away mid-action.
+   */
+  nativeDisabled: boolean;
+}
+
+export interface ButtonLocaleText {
+  /** Announced while the button is busy. */
+  loading: string;
+}

package/source/components/button/index.ts

@@ -0,0 +1,5 @@
+export { Button } from "./react/Button";
+export type { ButtonProps } from "./react/Button";
+export { defaultButtonText } from "./react/locale";
+export type { ButtonRenderProps, ButtonSlot } from "./react/props";
+export * from "./core";