@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/badge/react/Badge.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+import { formatCount, showCount } from "../core/count";
+import type { BadgeAppearance, BadgeSize, BadgeVariant } from "../core/types";
+import { cx, type BadgeSlot } from "./props";
+
+export interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+  children?: ReactNode;
+  /** Default `neutral`. */
+  variant?: BadgeVariant;
+  /** Default `soft`. */
+  appearance?: BadgeAppearance;
+  /** Default `md`. */
+  size?: BadgeSize;
+  /** A number instead of children. Above `max` it reads "99+". */
+  count?: number;
+  /** Where the count stops. Default 99. */
+  max?: number;
+  /** Show a count of zero. Default false: an empty counter is noise. */
+  showZero?: boolean;
+  /** Format the number, e.g. with `Intl.NumberFormat`. */
+  formatValue?(value: number): string;
+  /** A small filled circle before the label, for a status. */
+  dot?: boolean;
+  icon?: ReactNode;
+  classNames?: Partial<Record<BadgeSlot, string>>;
+  ref?: Ref<HTMLSpanElement>;
+}
+
+/**
+ * A short, static label: a status, a category, a count.
+ *
+ * It is text, not a control — nothing here is clickable or removable. Use
+ * **Tag** for something the user can take off, and a **Button** for something
+ * they can press.
+ */
+export function Badge(props: BadgeProps) {
+  const {
+    ref,
+    children,
+    variant = "neutral",
+    appearance = "soft",
+    size = "md",
+    count,
+    max = 99,
+    showZero = false,
+    formatValue,
+    dot = false,
+    icon,
+    className,
+    classNames,
+    ...rest
+  } = props;
+
+  const counted = count !== undefined;
+  if (counted && !showCount(count, showZero)) return null;
+  const label = counted ? formatCount(count, max, formatValue) : null;
+
+  return (
+    <span
+      {...rest}
+      ref={ref}
+      className={cx("bd-root", classNames?.root, className)}
+      data-variant={variant}
+      data-appearance={appearance}
+      data-size={size}
+      data-count={counted || undefined}
+    >
+      {dot && <span className={cx("bd-dot", classNames?.dot)} aria-hidden="true" />}
+      {icon && (
+        <span className={cx("bd-icon", classNames?.icon)} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <span className={cx("bd-label", classNames?.label)}>
+        {label ? (
+          <>
+            <span aria-hidden={label.spoken ? "true" : undefined}>{label.text}</span>
+            {/* "99+" read aloud is a guess at a number; this says what it means. */}
+            {label.spoken && <span className="bd-sr-only">{label.spoken}</span>}
+          </>
+        ) : (
+          children
+        )}
+      </span>
+    </span>
+  );
+}

package/source/components/badge/react/Tag.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useMemo, type HTMLAttributes, type ReactNode, type Ref } from "react";
+import { XIcon } from "../../shared/react/icons";
+import type { BadgeAppearance, BadgeLocaleText, BadgeSize, BadgeVariant } from "../core/types";
+import { defaultBadgeText } from "./locale";
+import { cx, type TagSlot } from "./props";
+
+export interface TagProps extends Omit<HTMLAttributes<HTMLSpanElement>, "onRemove"> {
+  children?: ReactNode;
+  variant?: BadgeVariant;
+  appearance?: BadgeAppearance;
+  size?: BadgeSize;
+  icon?: ReactNode;
+  /** Show a remove button. Without it a Tag is a Badge with a bit more padding. */
+  onRemove?(): void;
+  /** Names the remove button when the tag's own text is not a plain string. */
+  label?: string;
+  disabled?: boolean;
+  classNames?: Partial<Record<TagSlot, string>>;
+  localeText?: Partial<BadgeLocaleText>;
+  ref?: Ref<HTMLSpanElement>;
+}
+
+/**
+ * A chip the user can take off: a filter, a recipient, a selected value.
+ *
+ * The remove button carries the tag's own text in its name, so a screen reader
+ * says "Remove Berlin" rather than announcing a row of identical "Remove"
+ * buttons with no way to tell them apart.
+ */
+export function Tag(props: TagProps) {
+  const {
+    ref,
+    children,
+    variant = "neutral",
+    appearance = "soft",
+    size = "md",
+    icon,
+    onRemove,
+    label,
+    disabled = false,
+    className,
+    classNames,
+    localeText,
+    ...rest
+  } = props;
+
+  const text = useMemo(() => ({ ...defaultBadgeText, ...localeText }), [localeText]);
+  const name = label ?? (typeof children === "string" ? children : "");
+
+  return (
+    <span
+      {...rest}
+      ref={ref}
+      className={cx("bd-tag", classNames?.root, className)}
+      data-variant={variant}
+      data-appearance={appearance}
+      data-size={size}
+      data-disabled={disabled || undefined}
+    >
+      {icon && (
+        <span className={cx("bd-icon", classNames?.icon)} aria-hidden="true">
+          {icon}
+        </span>
+      )}
+      <span className={cx("bd-label", classNames?.label)}>{children}</span>
+      {onRemove && (
+        <button
+          type="button"
+          className={cx("bd-remove", classNames?.remove)}
+          aria-label={text.remove(name)}
+          title={text.remove(name)}
+          disabled={disabled}
+          onClick={onRemove}
+        >
+          <XIcon width={12} height={12} />
+        </button>
+      )}
+    </span>
+  );
+}

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

@@ -0,0 +1,5 @@
+import type { BadgeLocaleText } from "../core/types";
+
+export const defaultBadgeText: BadgeLocaleText = {
+  remove: (label: string) => `Remove ${label}`,
+};

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

@@ -0,0 +1,6 @@
+export type BadgeSlot = "root" | "dot" | "icon" | "label";
+
+export type TagSlot = "root" | "icon" | "label" | "remove";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/badge/styles.css

@@ -0,0 +1,203 @@
+/*
+ * Badge and Tag styles.
+ *
+ * One tinted pill in six variants and three appearances; the variant only ever
+ * sets --bd-accent, so adding one is a single rule. Tokens read the shared
+ * --gbs-* variables when they are set on an ancestor (set them on :root to
+ * theme every component at once). 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.
+ */
+
+.bd-root,
+.bd-tag {
+  --bd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --bd-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --bd-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --bd-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --bd-on-accent: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+  --bd-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --bd-accent-color: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --bd-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+  --bd-warning: var(--gbs-warning, light-dark(#b45309, #fbbf24));
+  --bd-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --bd-info: var(--gbs-info, var(--bd-accent-color));
+  --bd-font-size: calc(var(--gbs-font-size, var(--dg-font-size, 13px)) - 1px);
+  --bd-radius: 999px;
+  --bd-height: 20px;
+  --bd-px: 8px;
+  /* Neutral is the text colour rather than a hue, so it reads as "no state". */
+  --bd-accent: var(--bd-fg);
+
+  color-scheme: inherit;
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  max-width: 100%;
+  height: var(--bd-height);
+  padding: 0 var(--bd-px);
+  border: 1px solid transparent;
+  border-radius: var(--bd-radius);
+  font-size: var(--bd-font-size);
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+  vertical-align: middle;
+}
+
+:where(.dark, [data-theme="dark"]) :is(.bd-root, .bd-tag) {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) :is(.bd-root, .bd-tag) {
+  color-scheme: light;
+}
+
+:where(.bd-root, .bd-tag) *,
+:where(.bd-root, .bd-tag) *::before,
+:where(.bd-root, .bd-tag) *::after {
+  box-sizing: border-box;
+}
+
+.bd-root[data-variant="accent"],
+.bd-tag[data-variant="accent"] {
+  --bd-accent: var(--bd-accent-color);
+}
+.bd-root[data-variant="success"],
+.bd-tag[data-variant="success"] {
+  --bd-accent: var(--bd-success);
+}
+.bd-root[data-variant="warning"],
+.bd-tag[data-variant="warning"] {
+  --bd-accent: var(--bd-warning);
+}
+.bd-root[data-variant="danger"],
+.bd-tag[data-variant="danger"] {
+  --bd-accent: var(--bd-danger);
+}
+.bd-root[data-variant="info"],
+.bd-tag[data-variant="info"] {
+  --bd-accent: var(--bd-info);
+}
+
+/* --------------------------------------------------------- appearances */
+
+.bd-root[data-appearance="soft"],
+.bd-tag[data-appearance="soft"] {
+  background: color-mix(in oklab, var(--bd-accent) 12%, var(--bd-bg));
+  color: color-mix(in oklab, var(--bd-accent) 85%, var(--bd-fg));
+}
+.bd-root[data-appearance="solid"],
+.bd-tag[data-appearance="solid"] {
+  background: var(--bd-accent);
+  color: var(--bd-on-accent);
+}
+/* Neutral solid would be black on near-black text; invert it instead. */
+.bd-root[data-variant="neutral"][data-appearance="solid"],
+.bd-tag[data-variant="neutral"][data-appearance="solid"] {
+  background: var(--bd-fg);
+  color: var(--bd-bg);
+}
+.bd-root[data-appearance="outline"],
+.bd-tag[data-appearance="outline"] {
+  border-color: color-mix(in oklab, var(--bd-accent) 40%, var(--bd-border));
+  color: color-mix(in oklab, var(--bd-accent) 85%, var(--bd-fg));
+}
+
+.bd-root[data-size="sm"],
+.bd-tag[data-size="sm"] {
+  --bd-height: 17px;
+  --bd-px: 6px;
+  --bd-font-size: 11px;
+}
+
+/* A counter is a circle until it needs to be a pill. */
+.bd-root[data-count] {
+  justify-content: center;
+  min-width: var(--bd-height);
+  padding: 0 5px;
+  font-variant-numeric: tabular-nums;
+}
+
+.bd-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: currentColor;
+}
+.bd-icon {
+  display: inline-flex;
+  flex: none;
+}
+.bd-icon > svg {
+  width: 12px;
+  height: 12px;
+}
+.bd-label {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* ------------------------------------------------------------------ tag */
+
+.bd-tag {
+  --bd-px: 8px;
+  padding-inline-end: 4px;
+}
+.bd-tag:not(:has(.bd-remove)) {
+  padding-inline-end: var(--bd-px);
+}
+
+.bd-remove {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: 0;
+  border-radius: 50%;
+  background: none;
+  color: inherit;
+  opacity: 0.7;
+  cursor: pointer;
+}
+.bd-remove:hover:not(:disabled) {
+  background: color-mix(in oklab, currentColor 18%, transparent);
+  opacity: 1;
+}
+.bd-remove:focus-visible {
+  outline: 2px solid var(--bd-focus);
+  outline-offset: 1px;
+}
+.bd-remove:disabled {
+  cursor: not-allowed;
+}
+.bd-tag[data-disabled] {
+  opacity: 0.6;
+}
+
+.bd-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  border: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+@media (forced-colors: active) {
+  .bd-root,
+  .bd-tag {
+    border-color: CanvasText;
+  }
+  .bd-root[data-appearance="solid"],
+  .bd-tag[data-appearance="solid"] {
+    background: Highlight;
+    color: HighlightText;
+  }
+}

package/source/components/breadcrumb/README.md

@@ -0,0 +1,34 @@
+# Breadcrumb
+
+A breadcrumb trail for React 19, styled to match the rest of the library. No
+runtime dependencies besides React.
+
+```ts
+import { Breadcrumb } from "@/components/breadcrumb";
+import "@/components/breadcrumb/styles.css";
+```
+
+```tsx
+<Breadcrumb
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Invoices", href: "/invoices" },
+    { label: "INV-2026-0042" },
+  ]}
+  maxItems={4}
+  renderLink={(props) => <Link {...props} />}
+  structuredData={{ baseUrl: "https://app.example.com" }}
+/>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `items` | required | `{ label, href?, icon?, name?, onClick? }`, top level first; the last is the current page. |
+| `separator` | chevron | Between crumbs. |
+| `maxItems`, `itemsBeforeCollapse`, `itemsAfterCollapse` | —, `1`, `1` | Collapse the middle of long trails behind an ellipsis. |
+| `renderLink` | `<a>` | Draw links with your router. |
+| `structuredData` | `false` | Adds schema.org `BreadcrumbList` JSON-LD; pass `{ baseUrl }`. |
+| `size`, `className`, `classNames`, `localeText` | `md` | Slots: `root` `list` `item` `link` `current` `separator` `ellipsis`. |
+
+`collapseItems` and `toBreadcrumbJsonLd` are exported from the framework-free
+`core`.

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

@@ -0,0 +1,4 @@
+// Framework-free: trail collapsing and structured data.
+export { collapseItems, toBreadcrumbJsonLd } from "./trail";
+export type { JsonLdCrumb } from "./trail";
+export type * from "./types";

package/source/components/breadcrumb/core/trail.ts

@@ -0,0 +1,42 @@
+import type { CrumbSlot } from "./types";
+
+/**
+ * Collapses a long trail to its first and last crumbs with an ellipsis between,
+ * once it has more than `maxItems`. Returns the trail unchanged when it fits.
+ */
+export function collapseItems(
+  count: number,
+  maxItems?: number,
+  itemsBefore = 1,
+  itemsAfter = 1,
+): CrumbSlot[] {
+  const before = Math.max(0, itemsBefore);
+  const after = Math.max(1, itemsAfter);
+  const all: CrumbSlot[] = Array.from({ length: count }, (_, index) => ({ kind: "item", index }));
+  if (maxItems === undefined || count <= maxItems || before + after >= count) return all;
+
+  const hidden = Array.from({ length: count - before - after }, (_, offset) => before + offset);
+  return [...all.slice(0, before), { kind: "ellipsis", hidden }, ...all.slice(count - after)];
+}
+
+export interface JsonLdCrumb {
+  name: string;
+  href?: string;
+}
+
+/**
+ * schema.org `BreadcrumbList` data, which search engines use to show the trail
+ * in results. Relative links are resolved against `baseUrl`.
+ */
+export function toBreadcrumbJsonLd(items: readonly JsonLdCrumb[], baseUrl?: string) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    itemListElement: items.map((item, index) => ({
+      "@type": "ListItem",
+      position: index + 1,
+      name: item.name,
+      ...(item.href ? { item: baseUrl ? new URL(item.href, baseUrl).href : item.href } : {}),
+    })),
+  };
+}

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

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+
+export interface BreadcrumbItem {
+  label: ReactNode;
+  /** Omit for the current page or a crumb that isn't a link. */
+  href?: string;
+  icon?: ReactNode;
+  /** Plain-text name, for structured data when `label` isn't a string. */
+  name?: string;
+  /** Called on click, e.g. for client-side navigation without an href. */
+  onClick?(): void;
+}
+
+/** One position in the rendered trail. */
+export type CrumbSlot = { kind: "item"; index: number } | { kind: "ellipsis"; hidden: number[] };
+
+export interface BreadcrumbLocaleText {
+  label: string;
+  showMore(count: string): string;
+}

package/source/components/breadcrumb/index.ts

@@ -0,0 +1,5 @@
+export { Breadcrumb } from "./react/Breadcrumb";
+export type { BreadcrumbProps } from "./react/Breadcrumb";
+export { defaultBreadcrumbText } from "./react/locale";
+export type { BreadcrumbLinkProps, BreadcrumbSlot } from "./react/props";
+export * from "./core";