@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/button/styles.css

@@ -0,0 +1,232 @@
+/*
+ * Button 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.
+ */
+
+.bt-root {
+  --bt-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --bt-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --bt-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --bt-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --bt-subtle: var(--gbs-subtle, light-dark(#f4f4f5, #1c1c20));
+  --bt-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --bt-accent-fg: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+  --bt-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --bt-danger-fg: var(--gbs-danger-fg, light-dark(#ffffff, #1c0606));
+  --bt-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --bt-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --bt-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --bt-height: 36px;
+  --bt-px: 14px;
+  --bt-gap: 8px;
+
+  /* Per variant. */
+  --bt-fill: var(--bt-accent);
+  --bt-fill-hover: color-mix(in oklab, var(--bt-accent), var(--bt-fg) 12%);
+  --bt-ink: var(--bt-accent-fg);
+  --bt-line: var(--bt-accent);
+
+  color-scheme: inherit;
+  box-sizing: border-box;
+  position: relative;
+  display: inline-grid;
+  place-items: center;
+  height: var(--bt-height);
+  padding: 0 var(--bt-px);
+  border: 1px solid var(--bt-line);
+  border-radius: var(--bt-radius);
+  background: var(--bt-fill);
+  color: var(--bt-ink);
+  font: inherit;
+  font-size: var(--bt-font-size);
+  font-weight: 500;
+  line-height: 1;
+  white-space: nowrap;
+  text-decoration: none;
+  vertical-align: middle;
+  cursor: pointer;
+  user-select: none;
+  -webkit-tap-highlight-color: transparent;
+  transition:
+    background-color 120ms ease,
+    border-color 120ms ease,
+    color 120ms ease,
+    scale 120ms ease;
+}
+
+:where(.dark, [data-theme="dark"]) .bt-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .bt-root {
+  color-scheme: light;
+}
+
+:where(.bt-root) *,
+:where(.bt-root) *::before,
+:where(.bt-root) *::after {
+  box-sizing: border-box;
+}
+
+/* ------------------------------------------------------------ variants */
+
+.bt-root[data-variant="secondary"] {
+  --bt-fill: var(--bt-subtle);
+  --bt-fill-hover: color-mix(in oklab, var(--bt-subtle), var(--bt-fg) 8%);
+  --bt-ink: var(--bt-fg);
+  --bt-line: transparent;
+}
+.bt-root[data-variant="outline"] {
+  --bt-fill: var(--bt-bg);
+  --bt-fill-hover: var(--bt-hover);
+  --bt-ink: var(--bt-fg);
+  --bt-line: var(--bt-border);
+}
+.bt-root[data-variant="ghost"] {
+  --bt-fill: transparent;
+  --bt-fill-hover: var(--bt-hover);
+  --bt-ink: var(--bt-fg);
+  --bt-line: transparent;
+}
+.bt-root[data-variant="danger"] {
+  --bt-fill: var(--bt-danger);
+  --bt-fill-hover: color-mix(in oklab, var(--bt-danger), var(--bt-fg) 12%);
+  --bt-ink: var(--bt-danger-fg);
+  --bt-line: var(--bt-danger);
+}
+.bt-root[data-variant="link"] {
+  --bt-fill: transparent;
+  --bt-fill-hover: transparent;
+  --bt-ink: var(--bt-accent);
+  --bt-line: transparent;
+  --bt-px: 0px;
+  height: auto;
+  text-underline-offset: 3px;
+}
+.bt-root[data-variant="link"]:hover:not([aria-disabled="true"], :disabled) {
+  text-decoration: underline;
+}
+
+/* --------------------------------------------------------------- sizes */
+
+.bt-root[data-size="sm"] {
+  --bt-height: 30px;
+  --bt-px: 10px;
+  --bt-gap: 6px;
+  --bt-font-size: 12px;
+}
+.bt-root[data-size="lg"] {
+  --bt-height: 44px;
+  --bt-px: 18px;
+  --bt-gap: 10px;
+  --bt-font-size: 14px;
+}
+
+/* -------------------------------------------------------------- states */
+
+.bt-root:hover:not([aria-disabled="true"], :disabled) {
+  background: var(--bt-fill-hover);
+}
+.bt-root:active:not([aria-disabled="true"], :disabled) {
+  scale: 0.98;
+}
+.bt-root:focus-visible {
+  outline: 2px solid var(--bt-focus);
+  outline-offset: 2px;
+}
+.bt-root:disabled,
+.bt-root[aria-disabled="true"]:not([data-busy]) {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+.bt-root[data-busy] {
+  cursor: progress;
+}
+
+.bt-root[data-icon-only] {
+  width: var(--bt-height);
+  padding: 0;
+}
+.bt-root[data-full-width] {
+  width: 100%;
+}
+
+/* ------------------------------------------------------------- content */
+
+.bt-content,
+.bt-spinner {
+  grid-area: 1 / 1;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--bt-gap);
+  min-width: 0;
+}
+/* The label keeps its space while the spinner sits on top… */
+.bt-content[data-hidden] {
+  visibility: hidden;
+}
+/* …unless loading text replaces it. */
+.bt-root[data-loading-text] .bt-content {
+  display: none;
+}
+
+.bt-icon {
+  display: inline-flex;
+  flex: none;
+}
+.bt-icon > svg {
+  width: 1.15em;
+  height: 1.15em;
+}
+
+.bt-spinner-ring {
+  width: 1.15em;
+  height: 1.15em;
+  fill: none;
+  stroke: currentColor;
+  stroke-width: 2.5;
+  stroke-linecap: round;
+  stroke-dasharray: 30 100;
+  animation: bt-rotate 0.8s linear infinite;
+}
+@keyframes bt-rotate {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.bt-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bt-root {
+    transition: none;
+  }
+  .bt-root:active:not([aria-disabled="true"], :disabled) {
+    scale: none;
+  }
+  .bt-spinner-ring {
+    animation-duration: 2.4s;
+  }
+}
+
+@media (forced-colors: active) {
+  .bt-root {
+    border-color: ButtonText;
+  }
+}

package/source/components/card/README.md

@@ -0,0 +1,60 @@
+# Card
+
+A surface that groups related content, plus `Stat` for a single figure. For
+React 19, with no runtime dependencies besides React.
+
+```ts
+import { Card, CardHeader, CardBody, CardFooter, Stat, trendDirection } from "@/components/card";
+import "@/components/card/styles.css";
+```
+
+```tsx
+<Card>
+  <CardHeader title={<h3>Revenue</h3>} actions={<Menu trigger={<Button variant="ghost">…</Button>}>…</Menu>} />
+  <CardBody>
+    <Stat
+      label="This month"
+      value="£48,120"
+      trend={{ direction: trendDirection(12.4), label: "12.4%", description: "vs last month" }}
+    />
+  </CardBody>
+</Card>
+```
+
+## Card
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `variant` | `outlined` | `outlined`, `elevated` or `plain`. |
+| `padding` | `md` | `none`, `sm`, `md` or `lg`. |
+| `href` / `target` / `rel` | — | Makes the whole card a link. |
+| `interactive` | `false` | Hover and focus styles for a card clickable another way. |
+| `className`, `classNames`, `style` | — | Slots: `root`, `header`, `title`, `description`, `actions`, `body`, `footer`. |
+
+`CardHeader` takes `title`, `description` and `actions`. Pass your own heading
+element as the title — `<h3>Revenue</h3>` — so the page decides the level; a card
+is not always at the same depth in the outline.
+
+When `href` is set the card renders as an `<a>`, so keep other links and buttons
+out of it: nesting interactive elements is not valid HTML and traps the
+keyboard. Use `interactive` with your own handler instead.
+
+## Stat
+
+| Prop | Description |
+| --- | --- |
+| `label` / `value` | Always both: a number on its own means nothing. |
+| `trend` | `{ direction, label, invert?, description? }`. |
+| `help` | A note under the figure. |
+| `icon` | Drawn beside the label. |
+| `loading` | Placeholder bars, announced as "Loading". |
+
+`trend.invert` is for figures where down is the good outcome, such as churn or
+error rates: it changes the colour, and the arrow still points the way the
+number actually moved. The direction is also written out for screen readers, so
+the meaning never rests on colour alone.
+
+`trendDirection(change, threshold?)`, `isPositive(direction, invert?)` and
+`percentChange(from, to)` are framework-free helpers in `core/trend.ts`.
+`percentChange` returns `null` when the starting value is zero, because growth
+from nothing is not a percentage.

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

@@ -0,0 +1,4 @@
+// Framework-free: what counts as a rise or a fall.
+export { isPositive, percentChange, trendDirection } from "./trend";
+export type { TrendDirection } from "./trend";
+export type * from "./types";

package/source/components/card/core/trend.ts

@@ -0,0 +1,32 @@
+export type TrendDirection = "up" | "down" | "flat";
+
+/** Whether a change counts as a rise, a fall, or no real movement. */
+export function trendDirection(change: number, threshold = 0): TrendDirection {
+  if (!Number.isFinite(change)) return "flat";
+  if (change > threshold) return "up";
+  if (change < -threshold) return "down";
+  return "flat";
+}
+
+/**
+ * Whether a direction should be drawn as good news.
+ *
+ * Up is usually good, but not for churn, refunds or error rates, so `invert`
+ * flips it. Colour alone never carries the meaning: the arrow and the label do
+ * too.
+ */
+export function isPositive(direction: TrendDirection, invert = false): boolean | null {
+  if (direction === "flat") return null;
+  return invert ? direction === "down" : direction === "up";
+}
+
+/**
+ * A change as a percentage of where it started.
+ *
+ * Returns null when there is nothing to compare against: growth from zero is
+ * not "infinite percent", it is simply not a percentage.
+ */
+export function percentChange(from: number, to: number): number | null {
+  if (!Number.isFinite(from) || !Number.isFinite(to) || from === 0) return null;
+  return ((to - from) / Math.abs(from)) * 100;
+}

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

@@ -0,0 +1,5 @@
+export type CardVariant = "outlined" | "elevated" | "plain";
+export type CardPadding = "none" | "sm" | "md" | "lg";
+
+export type CardSlot = "root" | "header" | "title" | "description" | "actions" | "body" | "footer";
+export type StatSlot = "root" | "label" | "value" | "trend" | "help" | "icon";

package/source/components/card/index.ts

@@ -0,0 +1,5 @@
+export { Card, CardBody, CardFooter, CardHeader } from "./react/Card";
+export type { CardHeaderProps, CardProps } from "./react/Card";
+export { Stat } from "./react/Stat";
+export type { StatProps, StatTrend } from "./react/Stat";
+export * from "./core";

package/source/components/card/passport.json

@@ -0,0 +1,337 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Card",
+    "folder": "card",
+    "exports": [
+      "Card",
+      "CardBody",
+      "CardFooter",
+      "CardHeader",
+      "Stat"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/trend.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Card.tsx",
+      "react/Stat.tsx",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:549ddc0bab6442ba11768f3691605be509042dd42f313fc5d600d45b6aced521"
+  },
+  "props": [
+    {
+      "name": "actions",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Buttons or a menu, aligned to the end of the header.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "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": "children",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<CardSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "help",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "A note under the figure.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "hidden",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "href",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Makes the whole card a link. The card becomes an `<a>`, so keep any other\ninteractive content out of it — nested links and buttons are not valid.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "interactive",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Lifts the card on hover, for a card that is clickable by other means.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "label",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived",
+      "description": "What the figure is. Always visible — a number alone means nothing.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived",
+      "description": "Shows placeholder bars instead of the figure.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "padding",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "none",
+        "sm"
+      ],
+      "typeText": "CardPadding | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Padding applied to the header, body and footer. Default `md`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "rel",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "role",
+      "type": "other",
+      "typeText": "AriaRole | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "tabIndex",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "origin": "inherited"
+    },
+    {
+      "name": "target",
+      "type": "other",
+      "typeText": "import(\"react\").HTMLAttributeAnchorTarget | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Passed through when `href` is set.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "The heading. Wrap it in your own `h2`/`h3` to set the level.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "trend",
+      "type": "other",
+      "typeText": "StatTrend | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "value",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "elevated",
+        "outlined",
+        "plain"
+      ],
+      "typeText": "CardVariant | undefined",
+      "required": false,
+      "default": "outlined",
+      "origin": "derived",
+      "description": "Default `outlined`.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "inherits": [
+    {
+      "from": "HTMLAttributes<HTMLElement>",
+      "omitted": [
+        "title"
+      ],
+      "passthrough": true
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "header",
+    "title",
+    "description",
+    "actions",
+    "body",
+    "footer",
+    "label",
+    "value",
+    "trend",
+    "help",
+    "icon"
+  ],
+  "states": [
+    {
+      "attr": "data-direction"
+    },
+    {
+      "attr": "data-interactive"
+    },
+    {
+      "attr": "data-loading"
+    },
+    {
+      "attr": "data-padding",
+      "values": [
+        "lg",
+        "none",
+        "padding",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-positive",
+      "values": [
+        "false",
+        "true"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "elevated",
+        "outlined",
+        "plain",
+        "variant"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 27,
+    "propsDescribed": 10,
+    "describedPct": 37,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}