@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/skeleton/README.md

@@ -0,0 +1,58 @@
+# Skeleton
+
+Placeholders for content that is loading, plus `Empty` for when there is nothing
+to show. For React 19, with no runtime dependencies besides React.
+
+```ts
+import { Skeleton, Empty } from "@/components/skeleton";
+import "@/components/skeleton/styles.css";
+```
+
+```tsx
+{loading ? (
+  <Skeleton lines={3} label="Loading activity" />
+) : items.length === 0 ? (
+  <Empty
+    title="No activity yet"
+    description="Once someone uploads a file, it will show up here."
+    actions={<Button onClick={invite}>Invite your team</Button>}
+  />
+) : (
+  <ActivityList items={items} />
+)}
+```
+
+## Skeleton
+
+| Prop | Default | Description |
+| --- | --- | --- |
+| `variant` | `text` | `text`, `circle` or `rect`. |
+| `lines` / `lastLineWidth` | `1` / `60` | Bars for `text`, and how short the last one is. |
+| `width` / `height` / `radius` | — | A number is pixels; a string is used as given. |
+| `animation` | `pulse` | `pulse`, `wave` or `none`. |
+| `label` | — | Announced while the placeholder is up. |
+| `className`, `classNames`, `style` | — | Slots: `root`, `line`. |
+
+The bars are hidden from assistive technology — a screen reader gains nothing
+from the shape of a grey box. Use `label` here, or say the region is busy where
+that makes more sense, so the wait is announced once rather than twice.
+
+With more than one line the last is drawn short, because real text does not end
+flush with the margin. A single line stays full width: one short bar reads as a
+label rather than a sentence still loading.
+
+Both animations stop under `prefers-reduced-motion`.
+
+## Empty
+
+| Prop | Description |
+| --- | --- |
+| `title` | What is missing, in a few words. |
+| `description` | Why, and what to do about it. |
+| `icon` | Decorative; hidden from assistive technology. |
+| `actions` | The way out — usually one button. |
+| `size` | `sm`, `md` or `lg`. `sm` suits a panel inside a page. |
+
+It is a normal region, not a live one: an empty result is part of the page
+rather than an alert, and a search that finds nothing should not interrupt what
+someone is reading.

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

@@ -0,0 +1,3 @@
+// Framework-free: the shape of the placeholder.
+export { lineWidths, toLength } from "./lines";
+export type * from "./types";

package/source/components/skeleton/core/lines.ts

@@ -0,0 +1,25 @@
+/**
+ * The widths of the placeholder lines in a block of text.
+ *
+ * Real paragraphs do not end flush with the margin, so the last line is drawn
+ * short. One line is left full width: a single short bar reads as a label, not
+ * as a sentence still loading.
+ */
+export function lineWidths(lines: number, lastLineWidth = 60): string[] {
+  const count = Math.max(0, Math.floor(lines));
+  if (count === 0) return [];
+  return Array.from({ length: count }, (_, index) =>
+    index === count - 1 && count > 1 ? `${clampPercent(lastLineWidth)}%` : "100%",
+  );
+}
+
+function clampPercent(value: number): number {
+  if (!Number.isFinite(value)) return 100;
+  return Math.min(100, Math.max(10, value));
+}
+
+/** A CSS length from a number of pixels or a string that is already one. */
+export function toLength(value: number | string | undefined): string | undefined {
+  if (value === undefined) return undefined;
+  return typeof value === "number" ? `${value}px` : value;
+}

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

@@ -0,0 +1,5 @@
+export type SkeletonVariant = "text" | "circle" | "rect";
+export type SkeletonAnimation = "pulse" | "wave" | "none";
+
+export type SkeletonSlot = "root" | "line";
+export type EmptySlot = "root" | "icon" | "title" | "description" | "actions";

package/source/components/skeleton/index.ts

@@ -0,0 +1,5 @@
+export { Skeleton } from "./react/Skeleton";
+export type { SkeletonProps } from "./react/Skeleton";
+export { Empty } from "./react/Empty";
+export type { EmptyProps } from "./react/Empty";
+export * from "./core";

package/source/components/skeleton/passport.json

@@ -0,0 +1,251 @@
+{
+  "passportVersion": "1.0.0",
+  "identity": {
+    "component": "Skeleton",
+    "folder": "skeleton",
+    "exports": [
+      "Empty",
+      "Skeleton"
+    ]
+  },
+  "source": {
+    "libraryVersion": "2.4.0",
+    "files": [
+      "core/index.ts",
+      "core/lines.ts",
+      "core/types.ts",
+      "index.ts",
+      "react/Empty.tsx",
+      "react/Skeleton.tsx",
+      "react/props.ts"
+    ],
+    "sourceHash": "sha256:aac81a69f1b35c3bb20dcfccff178d25e0b735f9e63847a888b3904924111f0b"
+  },
+  "props": [
+    {
+      "name": "actions",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "The way out — usually one button, occasionally two.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "animation",
+      "type": "enum",
+      "values": [
+        "none",
+        "pulse",
+        "wave"
+      ],
+      "typeText": "SkeletonAnimation | undefined",
+      "required": false,
+      "default": "pulse",
+      "origin": "derived",
+      "description": "Default `pulse`. Reduced-motion settings turn any of them off.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "className",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "classNames",
+      "type": "other",
+      "typeText": "Partial<Record<SkeletonSlot, string>> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "description",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Why it is empty, and what to do about it.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "height",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "icon",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": false,
+      "origin": "derived",
+      "description": "Decorative: an illustration or icon above the title.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "typeText": "string | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Announced while the placeholder is up. Leave it out inside a region that\nalready says it is busy — two announcements are worse than one.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "lastLineWidth",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 60,
+      "origin": "derived",
+      "description": "Width of the last line as a percentage, for `text`. Default 60.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "lines",
+      "type": "number",
+      "typeText": "number | undefined",
+      "required": false,
+      "default": 1,
+      "origin": "derived",
+      "description": "Number of bars, for `text`. Default 1.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "radius",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "Corner radius for `rect`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "ref",
+      "type": "other",
+      "typeText": "Ref<HTMLDivElement> | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "size",
+      "type": "enum",
+      "values": [
+        "lg",
+        "md",
+        "sm"
+      ],
+      "typeText": "'sm' | 'md' | 'lg' | undefined",
+      "required": false,
+      "default": "md",
+      "origin": "derived",
+      "description": "Default `md`. `sm` suits an empty panel inside a page.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "style",
+      "type": "other",
+      "typeText": "CSSProperties | undefined",
+      "required": false,
+      "origin": "derived"
+    },
+    {
+      "name": "title",
+      "type": "other",
+      "typeText": "ReactNode",
+      "required": true,
+      "origin": "derived",
+      "description": "What is missing, in a few words.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "variant",
+      "type": "enum",
+      "values": [
+        "circle",
+        "rect",
+        "text"
+      ],
+      "typeText": "SkeletonVariant | undefined",
+      "required": false,
+      "default": "text",
+      "origin": "derived",
+      "description": "Default `text`.",
+      "descriptionOrigin": "jsdoc"
+    },
+    {
+      "name": "width",
+      "type": "other",
+      "typeText": "string | number | undefined",
+      "required": false,
+      "origin": "derived",
+      "description": "A number is pixels; a string is used as given.",
+      "descriptionOrigin": "jsdoc"
+    }
+  ],
+  "events": [],
+  "slots": [
+    "root",
+    "line",
+    "icon",
+    "title",
+    "description",
+    "actions"
+  ],
+  "states": [
+    {
+      "attr": "data-animation",
+      "values": [
+        "animation",
+        "pulse",
+        "wave"
+      ]
+    },
+    {
+      "attr": "data-lines"
+    },
+    {
+      "attr": "data-size",
+      "values": [
+        "lg",
+        "sm"
+      ]
+    },
+    {
+      "attr": "data-theme",
+      "values": [
+        "dark",
+        "light"
+      ]
+    },
+    {
+      "attr": "data-variant",
+      "values": [
+        "circle",
+        "rect",
+        "text",
+        "variant"
+      ]
+    }
+  ],
+  "accessibility": {
+    "supplied": [],
+    "required": []
+  },
+  "composition": {},
+  "operations": {},
+  "intentDomains": [],
+  "safeMutations": {},
+  "examples": [],
+  "coverage": {
+    "propsTotal": 17,
+    "propsDescribed": 12,
+    "describedPct": 71,
+    "authoredSections": [
+      "accessibility"
+    ]
+  }
+}

package/source/components/skeleton/react/Empty.tsx

@@ -0,0 +1,51 @@
+"use client";
+
+import type { CSSProperties, ReactNode } from "react";
+import type { EmptySlot } from "../core/types";
+import { cx } from "./props";
+
+export interface EmptyProps {
+  /** What is missing, in a few words. */
+  title: ReactNode;
+  /** Why it is empty, and what to do about it. */
+  description?: ReactNode;
+  /** Decorative: an illustration or icon above the title. */
+  icon?: ReactNode;
+  /** The way out — usually one button, occasionally two. */
+  actions?: ReactNode;
+  /** Default `md`. `sm` suits an empty panel inside a page. */
+  size?: "sm" | "md" | "lg";
+  className?: string;
+  classNames?: Partial<Record<EmptySlot, string>>;
+  style?: CSSProperties;
+}
+
+/**
+ * The state a list, table or panel shows when there is nothing in it.
+ *
+ * It is a normal region rather than a live one: an empty result is part of the
+ * page, not an alert, and a search that returns nothing should not interrupt
+ * what someone is reading. Say what is missing and offer the way out.
+ */
+export function Empty(props: EmptyProps) {
+  const { title, description, icon, actions, size = "md", className, classNames, style } = props;
+
+  return (
+    <div
+      className={cx("em-root", classNames?.root, className)}
+      style={style}
+      data-size={size}
+    >
+      {icon && (
+        <div className={cx("em-icon", classNames?.icon)} aria-hidden="true">
+          {icon}
+        </div>
+      )}
+      <p className={cx("em-title", classNames?.title)}>{title}</p>
+      {description && (
+        <p className={cx("em-description", classNames?.description)}>{description}</p>
+      )}
+      {actions && <div className={cx("em-actions", classNames?.actions)}>{actions}</div>}
+    </div>
+  );
+}

package/source/components/skeleton/react/Skeleton.tsx

@@ -0,0 +1,92 @@
+"use client";
+
+import type { CSSProperties, Ref } from "react";
+import { lineWidths, toLength } from "../core/lines";
+import type { SkeletonAnimation, SkeletonSlot, SkeletonVariant } from "../core/types";
+import { cx } from "./props";
+
+export interface SkeletonProps {
+  /** Default `text`. */
+  variant?: SkeletonVariant;
+  /** Number of bars, for `text`. Default 1. */
+  lines?: number;
+  /** Width of the last line as a percentage, for `text`. Default 60. */
+  lastLineWidth?: number;
+  /** A number is pixels; a string is used as given. */
+  width?: number | string;
+  height?: number | string;
+  /** Corner radius for `rect`. */
+  radius?: number | string;
+  /** Default `pulse`. Reduced-motion settings turn any of them off. */
+  animation?: SkeletonAnimation;
+  /**
+   * Announced while the placeholder is up. Leave it out inside a region that
+   * already says it is busy — two announcements are worse than one.
+   */
+  label?: string;
+  className?: string;
+  classNames?: Partial<Record<SkeletonSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * A placeholder in the shape of the content that is loading.
+ *
+ * It is hidden from assistive technology: a screen reader gains nothing from
+ * being told the shape of a grey box. Use `label`, or say the region is busy
+ * where it makes more sense, so the wait is announced once.
+ */
+export function Skeleton(props: SkeletonProps) {
+  const {
+    ref,
+    variant = "text",
+    lines = 1,
+    lastLineWidth = 60,
+    width,
+    height,
+    radius,
+    animation = "pulse",
+    label,
+    className,
+    classNames,
+    style,
+  } = props;
+
+  const shared = {
+    className: cx("sk-root", classNames?.root, className),
+    "data-variant": variant,
+    "data-animation": animation,
+    style: {
+      ...style,
+      "--sk-width": toLength(width),
+      "--sk-height": toLength(height),
+      "--sk-radius": toLength(radius),
+    } as CSSProperties,
+  };
+
+  // One shape for every variant: bars hidden from assistive technology, and an
+  // optional spoken label beside them. A conditional `aria-hidden` on the root
+  // would swallow that label in some variants and not others.
+  const widths = variant === "text" ? lineWidths(lines, lastLineWidth) : ["100%"];
+
+  return (
+    <div ref={ref} {...shared} data-lines={variant === "text" ? lines : undefined}>
+      {widths.map((lineWidth, index) => (
+        <div
+          // The bars are decoration with no identity of their own, so their
+          // position is the only key there is.
+          key={index}
+          className={cx("sk-line", classNames?.line)}
+          style={{ width: lineWidth }}
+          aria-hidden="true"
+        />
+      ))}
+      {label && (
+        <span className="sk-sr-only" role="status">
+          {label}
+        </span>
+      )}
+    </div>
+  );
+}

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

@@ -0,0 +1,4 @@
+export type { EmptySlot, SkeletonSlot } from "../core/types";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/skeleton/styles.css

@@ -0,0 +1,185 @@
+/*
+ * Skeleton and Empty 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.
+ */
+
+.sk-root,
+.em-root {
+  --sk-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --sk-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --sk-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --sk-base: var(--gbs-skeleton, var(--gbs-hover, var(--dg-hover, light-dark(#ececee, #232329))));
+  --sk-sheen: light-dark(rgb(255 255 255 / 0.65), rgb(255 255 255 / 0.06));
+  --sk-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --sk-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --sk-duration: 1.4s;
+
+  color-scheme: inherit;
+  font-size: var(--sk-font-size);
+  line-height: 1.5;
+}
+
+:where(.dark, [data-theme="dark"]) :is(.sk-root, .em-root) {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) :is(.sk-root, .em-root) {
+  color-scheme: light;
+}
+
+:where(.sk-root, .em-root) *,
+:where(.sk-root, .em-root) *::before,
+:where(.sk-root, .em-root) *::after {
+  box-sizing: border-box;
+}
+
+/* ------------------------------------------------------------ skeleton */
+
+.sk-root {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: var(--sk-width, 100%);
+  height: var(--sk-height);
+}
+
+.sk-line {
+  flex: none;
+  height: 100%;
+  border-radius: var(--sk-radius);
+  background: var(--sk-base);
+}
+
+/* Text bars are sized from the font, so a paragraph placeholder takes the
+   space the paragraph will. */
+.sk-root[data-variant="text"] {
+  height: var(--sk-height);
+}
+.sk-root[data-variant="text"] .sk-line {
+  height: var(--sk-height, 0.85em);
+  border-radius: 4px;
+}
+
+.sk-root[data-variant="circle"] {
+  width: var(--sk-width, 40px);
+  height: var(--sk-height, var(--sk-width, 40px));
+}
+.sk-root[data-variant="circle"] .sk-line {
+  border-radius: 50%;
+}
+
+.sk-root[data-variant="rect"] {
+  height: var(--sk-height, 80px);
+}
+
+.sk-root[data-animation="pulse"] .sk-line {
+  animation: sk-pulse var(--sk-duration) ease-in-out infinite;
+}
+@keyframes sk-pulse {
+  50% {
+    opacity: 0.45;
+  }
+}
+
+.sk-root[data-animation="wave"] .sk-line {
+  position: relative;
+  overflow: hidden;
+}
+.sk-root[data-animation="wave"] .sk-line::after {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background: linear-gradient(90deg, transparent, var(--sk-sheen), transparent);
+  animation: sk-wave var(--sk-duration) linear infinite;
+}
+@keyframes sk-wave {
+  from {
+    translate: -100% 0;
+  }
+  to {
+    translate: 100% 0;
+  }
+}
+
+.sk-sr-only,
+.em-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  border: 0;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+/* --------------------------------------------------------------- empty */
+
+.em-root {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  padding: 40px 24px;
+  color: var(--sk-fg);
+  text-align: center;
+  text-wrap: pretty;
+}
+.em-root[data-size="sm"] {
+  padding: 24px 16px;
+}
+.em-root[data-size="lg"] {
+  padding: 64px 24px;
+}
+
+.em-icon {
+  display: inline-flex;
+  margin-bottom: 4px;
+  color: var(--sk-muted);
+}
+.em-root[data-size="sm"] .em-icon {
+  margin-bottom: 0;
+}
+
+.em-title {
+  margin: 0;
+  font-size: 1.05em;
+  font-weight: 600;
+}
+.em-root[data-size="lg"] .em-title {
+  font-size: 1.2em;
+}
+
+.em-description {
+  max-width: 46ch;
+  margin: 0;
+  color: var(--sk-muted);
+}
+
+.em-actions {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 8px;
+  margin-top: 10px;
+}
+
+/* Movement that repeats forever is the kind reduced-motion means. */
+@media (prefers-reduced-motion: reduce) {
+  .sk-root .sk-line,
+  .sk-root .sk-line::after {
+    animation: none;
+  }
+}
+
+@media (forced-colors: active) {
+  .sk-line {
+    border: 1px solid CanvasText;
+  }
+}