@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/toaster/styles.css

@@ -0,0 +1,282 @@
+/*
+ * Toaster styles.
+ *
+ * Tokens read the shared --gbs-* variables when they are set on an ancestor
+ * (toasts render in a portal on <body>, so set them on :root) 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.
+ */
+
+.ts-region {
+  --ts-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --ts-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --ts-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --ts-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --ts-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --ts-accent: var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa)));
+  --ts-accent-fg: var(--gbs-accent-fg, var(--dg-accent-fg, light-dark(#ffffff, #0b1220)));
+  --ts-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --ts-shadow: var(--gbs-shadow, var(--dg-shadow, 0 10px 30px -8px light-dark(rgb(0 0 0 / 0.18), rgb(0 0 0 / 0.6))));
+  --ts-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --ts-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --ts-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+  --ts-error: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --ts-warning: var(--gbs-warning, light-dark(#d97706, #fbbf24));
+  --ts-info: var(--gbs-info, var(--gbs-accent, var(--dg-accent, light-dark(#2563eb, #60a5fa))));
+  --ts-width: 356px;
+  --ts-offset: 16px;
+  --ts-gap: 8px;
+  --ts-z-index: 2147483000;
+
+  color-scheme: inherit;
+  position: fixed;
+  z-index: var(--ts-z-index);
+  width: var(--ts-width);
+  max-width: calc(100vw - 2 * var(--ts-offset));
+  font-size: var(--ts-font-size);
+  line-height: 1.4;
+  color: var(--ts-fg);
+  /* The region spans the stack; only the toasts themselves take clicks. */
+  pointer-events: none;
+}
+
+:where(.dark, [data-theme="dark"]) .ts-region {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .ts-region {
+  color-scheme: light;
+}
+
+:where(.ts-region) *,
+:where(.ts-region) *::before,
+:where(.ts-region) *::after {
+  box-sizing: border-box;
+}
+
+/* ------------------------------------------------------------ placement */
+
+.ts-region[data-position^="top"] {
+  top: var(--ts-offset);
+  --ts-enter-y: -8px;
+}
+.ts-region[data-position^="bottom"] {
+  bottom: var(--ts-offset);
+  --ts-enter-y: 8px;
+}
+.ts-region[data-position$="left"] {
+  left: var(--ts-offset);
+}
+.ts-region[data-position$="right"] {
+  right: var(--ts-offset);
+}
+.ts-region[data-position$="center"] {
+  left: 50%;
+  translate: -50% 0;
+}
+
+@media (max-width: 600px) {
+  .ts-region {
+    right: var(--ts-offset);
+    left: var(--ts-offset);
+    width: auto;
+    max-width: none;
+    translate: none;
+  }
+}
+
+.ts-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--ts-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+  outline: none;
+}
+/* Newest toast sits nearest the screen edge. */
+.ts-region[data-position^="bottom"] .ts-list {
+  flex-direction: column-reverse;
+}
+.ts-list:focus-visible {
+  outline: 2px solid var(--ts-focus);
+  outline-offset: 4px;
+  border-radius: var(--ts-radius);
+}
+
+/* --------------------------------------------------------------- toast */
+
+.ts-toast {
+  --ts-type-color: transparent;
+
+  position: relative;
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  width: 100%;
+  padding-block: 12px;
+  padding-inline: 14px 10px;
+  overflow: hidden;
+  border: 1px solid var(--ts-border);
+  border-radius: var(--ts-radius);
+  background: var(--ts-bg);
+  color: var(--ts-fg);
+  box-shadow: var(--ts-shadow);
+  pointer-events: auto;
+  outline: none;
+  touch-action: pan-y;
+  opacity: 1;
+  translate: var(--ts-swipe, 0px) 0;
+  transition:
+    opacity 200ms ease,
+    translate 200ms ease;
+}
+@starting-style {
+  .ts-toast {
+    opacity: 0;
+    translate: 0 var(--ts-enter-y, 8px);
+  }
+}
+.ts-toast[data-swiping] {
+  transition: none;
+  cursor: grabbing;
+}
+.ts-toast[data-state="closing"] {
+  opacity: 0;
+  pointer-events: none;
+}
+.ts-toast:focus-visible {
+  outline: 2px solid var(--ts-focus);
+  outline-offset: -2px;
+}
+
+/* A thin bar on the reading-start edge carries the type's color. */
+.ts-toast::before {
+  content: "";
+  position: absolute;
+  inset-block: 0;
+  inset-inline-start: 0;
+  width: 3px;
+  background: var(--ts-type-color);
+}
+.ts-toast[data-type="success"] {
+  --ts-type-color: var(--ts-success);
+}
+.ts-toast[data-type="error"] {
+  --ts-type-color: var(--ts-error);
+}
+.ts-toast[data-type="warning"] {
+  --ts-type-color: var(--ts-warning);
+}
+.ts-toast[data-type="info"] {
+  --ts-type-color: var(--ts-info);
+}
+
+.ts-icon {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  margin-top: 1px;
+  color: var(--ts-type-color);
+}
+.ts-toast:is([data-type="default"], [data-type="loading"]) .ts-icon {
+  color: var(--ts-muted);
+}
+
+.ts-content {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow-wrap: anywhere;
+}
+.ts-title {
+  font-weight: 600;
+}
+.ts-description {
+  margin-top: 2px;
+  color: var(--ts-muted);
+}
+
+.ts-actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  align-self: center;
+  gap: 6px;
+}
+.ts-button {
+  height: 28px;
+  padding: 0 10px;
+  border: 1px solid var(--ts-border);
+  border-radius: 6px;
+  background: var(--ts-bg);
+  color: inherit;
+  font: inherit;
+  font-weight: 500;
+  white-space: nowrap;
+  cursor: pointer;
+}
+.ts-button:hover {
+  background: var(--ts-hover);
+}
+.ts-button[data-variant="action"] {
+  border-color: var(--ts-accent);
+  background: var(--ts-accent);
+  color: var(--ts-accent-fg);
+}
+.ts-button[data-variant="action"]:hover {
+  background: color-mix(in oklab, var(--ts-accent), var(--ts-fg) 12%);
+}
+.ts-button:focus-visible {
+  outline: 2px solid var(--ts-focus);
+  outline-offset: 1px;
+}
+
+.ts-close {
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--ts-muted);
+  cursor: pointer;
+}
+.ts-close:hover {
+  background: var(--ts-hover);
+  color: var(--ts-fg);
+}
+.ts-close:focus-visible {
+  outline: 2px solid var(--ts-focus);
+  outline-offset: 1px;
+}
+
+.ts-spinner {
+  animation: ts-spin 0.7s linear infinite;
+}
+@keyframes ts-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ts-toast {
+    transition: none;
+  }
+  .ts-spinner {
+    animation-duration: 2s;
+  }
+}
+
+@media (forced-colors: active) {
+  .ts-toast {
+    border-color: CanvasText;
+  }
+  .ts-toast::before {
+    background: Highlight;
+  }
+}

package/source/components/tooltip/README.md

@@ -0,0 +1,43 @@
+# Tooltip
+
+A short label shown on hover or keyboard focus, for React 19, following the
+WAI-ARIA tooltip pattern. No runtime dependencies besides React.
+
+```ts
+import { Tooltip } from "@/components/tooltip";
+import "@/components/tooltip/styles.css";
+```
+
+```tsx
+<Tooltip content="Export as CSV">
+  <Button variant="ghost" aria-label="Export"><DownloadIcon /></Button>
+</Tooltip>
+```
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `content` | — | The label. A few words; anything longer belongs in a Popover. |
+| `children` | — | A single element, cloned with a ref, handlers and `aria-describedby`. |
+| `side` / `align` / `gap` | `top` / `center` / `6` | Flips and clamps to stay on screen. |
+| `delay` | `400` | Wait before showing on hover. Keyboard focus never waits. |
+| `closeDelay` | `120` | Wait before hiding, so crossing a small gap does not flicker. |
+| `disabled` | `false` | Never show it. |
+| `className`, `classNames`, `style` | — | Slots: `root`, `content`. |
+
+## What it will not do
+
+**It describes, it does not name.** The tooltip is wired with
+`aria-describedby`, so the control keeps its own accessible name — an icon
+button still needs an `aria-label`. A tooltip is not a substitute for one.
+
+**Touch devices never see it.** A tooltip on tap covers the thing that was
+tapped. Anything essential must be available another way.
+
+**It never takes focus** and is `pointer-events: none`, so it cannot be hovered
+or clicked. Content that needs interaction belongs in a Popover.
+
+`Escape` dismisses it wherever focus is, and clicking the control hides it
+rather than leaving it over whatever the click did.
+
+The timing rules are framework-free in `core/visibility.ts` and unit-tested
+there. Placement comes from `shared/core/position.ts`.

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

@@ -0,0 +1,4 @@
+// Framework-free: when the tooltip should be shown, and by what.
+export { isHoverPointer, nextVisibility } from "./visibility";
+export type { TooltipTrigger, TooltipTriggers } from "./visibility";
+export type * from "./types";

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

@@ -0,0 +1,4 @@
+export type TooltipSide = "top" | "bottom" | "left" | "right";
+export type TooltipAlign = "start" | "center" | "end";
+
+export type TooltipSlot = "root" | "content";

package/source/components/tooltip/core/visibility.ts

@@ -0,0 +1,34 @@
+/** What is currently asking for the tooltip to be shown. */
+export interface TooltipTriggers {
+  hovered: boolean;
+  focused: boolean;
+}
+
+export type TooltipTrigger = keyof TooltipTriggers;
+
+/**
+ * Whether the tooltip should be open, and after how long.
+ *
+ * Hover waits, so running the pointer across a toolbar does not flash a tooltip
+ * over every button. Keyboard focus does not: someone who tabbed to a control
+ * has already committed to it, and a delay just looks broken.
+ */
+export function nextVisibility(
+  triggers: TooltipTriggers,
+  delays: { open: number; close: number },
+): { open: boolean; delay: number } {
+  if (triggers.focused) return { open: true, delay: 0 };
+  if (triggers.hovered) return { open: true, delay: delays.open };
+  return { open: false, delay: delays.close };
+}
+
+/**
+ * Whether a pointer event should count as a hover at all.
+ *
+ * A touch "hover" is really a tap, and showing a tooltip on tap covers the
+ * thing that was tapped. Touch devices get nothing, which is why a tooltip must
+ * never carry information that is not also available another way.
+ */
+export function isHoverPointer(pointerType: string): boolean {
+  return pointerType !== "touch" && pointerType !== "pen";
+}

package/source/components/tooltip/index.ts

@@ -0,0 +1,3 @@
+export { Tooltip } from "./react/Tooltip";
+export type { TooltipProps } from "./react/Tooltip";
+export * from "./core";

package/source/components/tooltip/passport.json

@@ -0,0 +1,170 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Tooltip",
+    "folder": "tooltip",
+    "exports": [
+      "Tooltip"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/types.ts",
+      "core/visibility.ts",
+      "index.ts",
+      "react/Tooltip.tsx",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:27e564b384259c710f11e5795bbef73813368bd445d17f1d0562910a53dc23e8"
+  },
+  "props": [
+    {
+      "name": "align",
+      "type": "enum",
+      "values": [
+        "center",
+        "end",
+        "start"
+      ],
+      "typeText": "TooltipAlign | undefined",
+      "required": false,
+      "default": "center",
+      "origin": "derived",
+      "description": "Default `center`, which is only meaningful with `side` top or bottom.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "children",
+      "type": "other",
+      "typeText": "ReactElement<{ [attribute: string]: unknown; }, string | import(\"react\").JSXElementConstructor<any>>",
+      "required": true,
+      "origin": "derived",
+      "description": "The control it describes: a single element, cloned with a ref, the pointer\r\nand focus handlers, and `aria-describedby`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<TooltipSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "closeDelay",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 120,
+      "origin": "derived",
+      "description": "Wait before hiding, in ms. Default 120, so crossing a gap does not flicker.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "content",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived",
+      "description": "The short label. Keep it to a few words.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "delay",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 400,
+      "origin": "derived",
+      "description": "Wait before showing on hover, in ms. Default 400. Focus never waits.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "typeText": "boolean | undefined",
+      "required": false,
+      "default": false,
+      "origin": "derived"
+    },
+    {
+      "name": "gap",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 6,
+      "origin": "derived",
+      "description": "Distance from the control. Default 6.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "id",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "side",
+      "type": "enum",
+      "values": [
+        "bottom",
+        "left",
+        "right",
+        "top"
+      ],
+      "typeText": "TooltipSide | undefined",
+      "required": false,
+      "default": "top",
+      "origin": "derived",
+      "description": "Default `top`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "content"
+  ],
+  "states": [
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 12,
+    "propsDescribed": 7,
+    "describedPct": 58,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}