@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/card/react/Card.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import type { AnchorHTMLAttributes, CSSProperties, HTMLAttributes, ReactNode, Ref } from "react";
+import type { CardPadding, CardSlot, CardVariant } from "../core/types";
+import { cx } from "./props";
+
+export interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  children?: ReactNode;
+  /** Default `outlined`. */
+  variant?: CardVariant;
+  /** Padding applied to the header, body and footer. Default `md`. */
+  padding?: CardPadding;
+  /**
+   * Makes the whole card a link. The card becomes an `<a>`, so keep any other
+   * interactive content out of it — nested links and buttons are not valid.
+   */
+  href?: string;
+  /** Passed through when `href` is set. */
+  target?: AnchorHTMLAttributes<HTMLAnchorElement>["target"];
+  rel?: string;
+  /** Lifts the card on hover, for a card that is clickable by other means. */
+  interactive?: boolean;
+  className?: string;
+  classNames?: Partial<Record<CardSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLElement>;
+}
+
+/**
+ * A surface that groups related content, with optional header, body and footer.
+ *
+ * Give it a heading through `CardHeader` rather than a bare `title` prop, so the
+ * page decides the heading level: a card is not always at the same depth.
+ */
+export function Card(props: CardProps) {
+  const {
+    ref,
+    children,
+    variant = "outlined",
+    padding = "md",
+    href,
+    target,
+    rel,
+    interactive = false,
+    className,
+    classNames,
+    style,
+    ...rest
+  } = props;
+
+  const shared = {
+    className: cx("cd-root", classNames?.root, className),
+    style,
+    "data-variant": variant,
+    "data-padding": padding,
+    "data-interactive": (interactive || href !== undefined) || undefined,
+    ...rest,
+  };
+
+  if (href !== undefined) {
+    return (
+      <a
+        {...shared}
+        ref={ref as Ref<HTMLAnchorElement>}
+        href={href}
+        target={target}
+        // Anything opening a new tab gets the safe default unless told otherwise.
+        rel={rel ?? (target === "_blank" ? "noreferrer" : undefined)}
+      >
+        {children}
+      </a>
+    );
+  }
+
+  return (
+    <div {...shared} ref={ref as Ref<HTMLDivElement>}>
+      {children}
+    </div>
+  );
+}
+
+export interface CardHeaderProps {
+  /** The heading. Wrap it in your own `h2`/`h3` to set the level. */
+  title?: ReactNode;
+  description?: ReactNode;
+  /** Buttons or a menu, aligned to the end of the header. */
+  actions?: ReactNode;
+  children?: ReactNode;
+  className?: string;
+  classNames?: Partial<Record<CardSlot, string>>;
+}
+
+export function CardHeader({
+  title,
+  description,
+  actions,
+  children,
+  className,
+  classNames,
+}: CardHeaderProps) {
+  return (
+    <div className={cx("cd-header", classNames?.header, className)}>
+      <div className="cd-heading">
+        {title && <div className={cx("cd-title", classNames?.title)}>{title}</div>}
+        {description && (
+          <div className={cx("cd-description", classNames?.description)}>{description}</div>
+        )}
+        {children}
+      </div>
+      {actions && <div className={cx("cd-actions", classNames?.actions)}>{actions}</div>}
+    </div>
+  );
+}
+
+export function CardBody({
+  children,
+  className,
+}: {
+  children?: ReactNode;
+  className?: string;
+}) {
+  return <div className={cx("cd-body", className)}>{children}</div>;
+}
+
+export function CardFooter({
+  children,
+  className,
+}: {
+  children?: ReactNode;
+  className?: string;
+}) {
+  return <div className={cx("cd-footer", className)}>{children}</div>;
+}

package/source/components/card/react/Stat.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { useId, type CSSProperties, type ReactNode } from "react";
+import { isPositive, type TrendDirection } from "../core/trend";
+import type { StatSlot } from "../core/types";
+import { cx } from "./props";
+
+export interface StatTrend {
+  /** `up`, `down` or `flat`. `trendDirection(change)` works this out for you. */
+  direction: TrendDirection;
+  /** What is shown beside the arrow, already formatted, e.g. "12.4%". */
+  label: ReactNode;
+  /**
+   * Down is the good outcome for this figure, as with churn or error rates.
+   * Only changes the colour; the arrow still points the way the number moved.
+   */
+  invert?: boolean;
+  /** Read out after the change, e.g. "since last month". */
+  description?: ReactNode;
+}
+
+export interface StatProps {
+  /** What the figure is. Always visible — a number alone means nothing. */
+  label: ReactNode;
+  value: ReactNode;
+  trend?: StatTrend;
+  /** A note under the figure. */
+  help?: ReactNode;
+  icon?: ReactNode;
+  /** Shows placeholder bars instead of the figure. */
+  loading?: boolean;
+  className?: string;
+  classNames?: Partial<Record<StatSlot, string>>;
+  style?: CSSProperties;
+}
+
+const ARROWS: Record<TrendDirection, string> = {
+  up: "M12 19V5M5 12l7-7 7 7",
+  down: "M12 5v14M19 12l-7 7-7-7",
+  flat: "M5 12h14",
+};
+
+/** The word behind the arrow, so the direction is not carried by colour alone. */
+const DIRECTION_TEXT: Record<TrendDirection, string> = {
+  up: "Up",
+  down: "Down",
+  flat: "No change",
+};
+
+/**
+ * A single figure with its label and, optionally, how it has changed.
+ *
+ * Put it inside a `Card` for a dashboard tile, or use it on its own in a row of
+ * summary numbers.
+ */
+export function Stat(props: StatProps) {
+  const { label, value, trend, help, icon, loading = false, className, classNames, style } = props;
+  const id = useId();
+  const positive = trend ? isPositive(trend.direction, trend.invert) : null;
+
+  return (
+    <div
+      className={cx("st-root", classNames?.root, className)}
+      style={style}
+      data-loading={loading || undefined}
+    >
+      <div className="st-head">
+        <span id={`${id}-label`} className={cx("st-label", classNames?.label)}>
+          {label}
+        </span>
+        {icon && (
+          <span className={cx("st-icon", classNames?.icon)} aria-hidden="true">
+            {icon}
+          </span>
+        )}
+      </div>
+
+      {loading ? (
+        <>
+          <div className="st-placeholder st-placeholder-value" />
+          <div className="st-placeholder st-placeholder-help" />
+          <span className="st-sr-only">Loading</span>
+        </>
+      ) : (
+        <>
+          <div
+            className={cx("st-value", classNames?.value)}
+            aria-labelledby={`${id}-label`}
+            role="figure"
+          >
+            {value}
+          </div>
+
+          {trend && (
+            <div
+              className={cx("st-trend", classNames?.trend)}
+              data-direction={trend.direction}
+              data-positive={positive === null ? undefined : positive}
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+                focusable="false"
+              >
+                <path d={ARROWS[trend.direction]} />
+              </svg>
+              <span className="st-sr-only">{DIRECTION_TEXT[trend.direction]}</span>
+              <span className="st-trend-label">{trend.label}</span>
+              {trend.description && (
+                <span className="st-trend-description">{trend.description}</span>
+              )}
+            </div>
+          )}
+
+          {help && <div className={cx("st-help", classNames?.help)}>{help}</div>}
+        </>
+      )}
+    </div>
+  );
+}

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

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

package/source/components/card/styles.css

@@ -0,0 +1,230 @@
+/*
+ * Card and Stat 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.
+ */
+
+.cd-root,
+.st-root {
+  --cd-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --cd-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --cd-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --cd-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --cd-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --cd-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --cd-success: var(--gbs-success, light-dark(#15803d, #4ade80));
+  --cd-danger: var(--gbs-danger, var(--dg-danger, light-dark(#dc2626, #f87171)));
+  --cd-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))));
+  --cd-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --cd-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --cd-px: 16px;
+
+  color-scheme: inherit;
+  font-size: var(--cd-font-size);
+  line-height: 1.5;
+  color: var(--cd-fg);
+}
+
+:where(.dark, [data-theme="dark"]) :is(.cd-root, .st-root) {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) :is(.cd-root, .st-root) {
+  color-scheme: light;
+}
+
+:where(.cd-root, .st-root) *,
+:where(.cd-root, .st-root) *::before,
+:where(.cd-root, .st-root) *::after {
+  box-sizing: border-box;
+}
+
+/* ---------------------------------------------------------------- card */
+
+.cd-root {
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+  border-radius: var(--cd-radius);
+  background: var(--cd-bg);
+  text-decoration: none;
+}
+.cd-root[data-variant="outlined"] {
+  border: 1px solid var(--cd-border);
+}
+.cd-root[data-variant="elevated"] {
+  border: 1px solid transparent;
+  box-shadow: var(--cd-shadow);
+}
+.cd-root[data-variant="plain"] {
+  background: transparent;
+}
+
+.cd-root[data-padding="none"] {
+  --cd-px: 0px;
+}
+.cd-root[data-padding="sm"] {
+  --cd-px: 12px;
+}
+.cd-root[data-padding="lg"] {
+  --cd-px: 24px;
+}
+
+.cd-root[data-interactive] {
+  cursor: pointer;
+  transition:
+    background-color 120ms ease,
+    box-shadow 120ms ease,
+    translate 120ms ease;
+}
+.cd-root[data-interactive]:hover {
+  background: var(--cd-hover);
+}
+.cd-root[data-variant="elevated"][data-interactive]:hover {
+  translate: 0 -1px;
+}
+.cd-root[data-interactive]:focus-visible {
+  outline: 2px solid var(--cd-focus);
+  outline-offset: 2px;
+}
+
+.cd-header {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+  padding: var(--cd-px) var(--cd-px) 0;
+}
+.cd-heading {
+  flex: 1 1 auto;
+  min-width: 0;
+}
+.cd-title {
+  font-size: 1.05em;
+  font-weight: 600;
+  line-height: 1.35;
+}
+.cd-description {
+  margin-top: 2px;
+  color: var(--cd-muted);
+}
+.cd-actions {
+  display: flex;
+  flex: none;
+  align-items: center;
+  gap: 4px;
+}
+
+.cd-body {
+  flex: 1 1 auto;
+  min-width: 0;
+  padding: var(--cd-px);
+}
+/* The header already spaces the top, so the body should not double it. */
+.cd-header + .cd-body {
+  padding-top: 12px;
+}
+
+.cd-footer {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 12px var(--cd-px);
+  border-top: 1px solid var(--cd-border);
+}
+
+/* ---------------------------------------------------------------- stat */
+
+.st-root {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  min-width: 0;
+}
+.st-head {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.st-label {
+  flex: 1 1 auto;
+  min-width: 0;
+  color: var(--cd-muted);
+  font-weight: 500;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.st-icon {
+  display: inline-flex;
+  flex: none;
+  color: var(--cd-muted);
+}
+.st-value {
+  font-size: 1.9em;
+  font-weight: 650;
+  font-variant-numeric: tabular-nums;
+  line-height: 1.15;
+  letter-spacing: -0.01em;
+}
+
+.st-trend {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  color: var(--cd-muted);
+}
+/* Colour is a second signal: the arrow and the visually hidden word carry
+   the direction on their own. */
+.st-trend[data-positive="true"] {
+  color: var(--cd-success);
+}
+.st-trend[data-positive="false"] {
+  color: var(--cd-danger);
+}
+.st-trend-label {
+  font-variant-numeric: tabular-nums;
+  font-weight: 500;
+}
+.st-trend-description {
+  color: var(--cd-muted);
+}
+
+.st-help {
+  color: var(--cd-muted);
+}
+
+.st-placeholder {
+  border-radius: 4px;
+  background: var(--cd-hover);
+}
+.st-placeholder-value {
+  width: 5ch;
+  height: 1.9em;
+}
+.st-placeholder-help {
+  width: 10ch;
+  height: 1em;
+}
+
+.st-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  border: 0;
+  clip-path: inset(50%);
+  white-space: nowrap;
+}
+
+@media (forced-colors: active) {
+  .cd-root[data-variant="elevated"] {
+    border-color: CanvasText;
+  }
+}

package/source/components/checkbox/README.md

@@ -0,0 +1,36 @@
+# Checkbox and CheckboxGroup
+
+Checkboxes for React 19, styled to match the rest of the library. The box is a
+real `<input type="checkbox">`, so forms, form libraries and assistive
+technology work as they do natively. No runtime dependencies besides React.
+
+```ts
+import { Checkbox, CheckboxGroup } from "@/components/checkbox";
+import "@/components/checkbox/styles.css";
+```
+
+```tsx
+<Checkbox label="Remember me" name="remember" checked={remember} onCheckedChange={setRemember} />
+
+<CheckboxGroup
+  label="Notify me by"
+  name="channels"
+  options={[{ value: "email", label: "Email" }, { value: "sms", label: "SMS" }]}
+  value={channels}
+  onValueChange={setChannels}
+  selectAll
+/>
+```
+
+**Checkbox:** `checked` / `defaultChecked` (`true`, `false`, `"indeterminate"`),
+`onCheckedChange`, `value`, `label`, `description`, `error`, `size`, `classNames`
+(`root` `control` `input` `label` `description` `error`), `ref` (the `<input>`), and
+every `<input>` attribute.
+
+**CheckboxGroup:** `value` / `defaultValue` / `onValueChange` (string arrays),
+`options` or `<Checkbox value>` children, `label` (legend), `description`,
+`error`, `required`, `disabled`, `name`, `size`, `orientation`, `selectAll`,
+`classNames` (`root` `legend` `description` `items` `error`), `localeText`.
+
+`toggleValue`, `groupState` and `toggleAll` are exported from the
+framework-free `core`.

package/source/components/checkbox/core/group.ts

@@ -0,0 +1,30 @@
+import type { CheckedState } from "./types";
+
+/** Adds or removes one value, keeping the order values were selected in. */
+export function toggleValue(values: readonly string[], value: string, checked: boolean): string[] {
+  const has = values.includes(value);
+  if (checked) return has ? [...values] : [...values, value];
+  return values.filter((item) => item !== value);
+}
+
+/** A "select all" box's state for the options in a group. */
+export function groupState(values: readonly string[], options: readonly { value: string }[]): CheckedState {
+  if (options.length === 0) return false;
+  const selected = options.filter((option) => values.includes(option.value)).length;
+  if (selected === 0) return false;
+  return selected === options.length ? true : "indeterminate";
+}
+
+/**
+ * What "select all" does: when every enabled option is already selected, clear
+ * them; otherwise select them all. Disabled options keep their state either way.
+ */
+export function toggleAll(
+  values: readonly string[],
+  options: readonly { value: string; disabled?: boolean }[],
+): string[] {
+  const enabled = options.filter((option) => !option.disabled).map((option) => option.value);
+  const allOn = enabled.every((value) => values.includes(value));
+  if (allOn) return values.filter((value) => !enabled.includes(value));
+  return [...values, ...enabled.filter((value) => !values.includes(value))];
+}

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

@@ -0,0 +1,3 @@
+// Framework-free: selection rules for checkbox groups.
+export { groupState, toggleAll, toggleValue } from "./group";
+export type * from "./types";

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

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+export type CheckboxSize = "sm" | "md" | "lg";
+
+/** `true`, `false`, or partly checked. */
+export type CheckedState = boolean | "indeterminate";
+
+export interface CheckboxOption {
+  value: string;
+  label: ReactNode;
+  description?: ReactNode;
+  disabled?: boolean;
+}
+
+export interface CheckboxLocaleText {
+  selectAll: string;
+}

package/source/components/checkbox/index.ts

@@ -0,0 +1,9 @@
+export { Checkbox } from "./react/Checkbox";
+export type { CheckboxProps } from "./react/Checkbox";
+export { CheckboxGroup } from "./react/CheckboxGroup";
+export type { CheckboxGroupProps } from "./react/CheckboxGroup";
+export { CheckboxGroupContext } from "./react/context";
+export type { CheckboxGroupContextValue } from "./react/context";
+export { defaultCheckboxText } from "./react/locale";
+export type { CheckboxGroupSlot, CheckboxSlot } from "./react/props";
+export * from "./core";