@grampro/kit 0.0.0-stage → 2.4.0

package/source/components/accordion/react/Accordion.tsx

@@ -0,0 +1,133 @@
+"use client";
+
+import {
+  useCallback,
+  useMemo,
+  type CSSProperties,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { useControllableState } from "../../shared/react/useControllableState";
+import { normalizeOpen, toggleOpen } from "../core/open";
+import type {
+  AccordionIconPosition,
+  AccordionItemData,
+  AccordionSize,
+  AccordionVariant,
+} from "../core/types";
+import { AccordionItem } from "./AccordionItem";
+import { AccordionContext, type AccordionContextValue } from "./context";
+import { cx, type AccordionSlot } from "./props";
+
+export interface AccordionProps {
+  /** Open panels, by value (controlled). */
+  value?: string[];
+  defaultValue?: string[];
+  onValueChange?(value: string[]): void;
+  /** Render these panels, or pass `<AccordionItem>` children. */
+  items?: readonly AccordionItemData[];
+  children?: ReactNode;
+  /** Allow more than one panel open at a time. Default false. */
+  multiple?: boolean;
+  /** Allow the open panel to be closed again. Default true. */
+  collapsible?: boolean;
+  /** Default `separated`. */
+  variant?: AccordionVariant;
+  /** Default `md`. */
+  size?: AccordionSize;
+  /** Which side the chevron sits on. Default `end`. */
+  iconPosition?: AccordionIconPosition;
+  className?: string;
+  classNames?: Partial<Record<AccordionSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLDivElement>;
+}
+
+/**
+ * Sections that open one at a time, built on `<details>` and `<summary>`.
+ *
+ * The browser owns the disclosure: the header is focusable, Enter and Space
+ * work, the panel is hidden from search and from the accessibility tree while
+ * closed, and Ctrl+F still finds text inside a closed panel in browsers that
+ * support it. None of that is implemented here.
+ *
+ * What is implemented is the accordion *around* the disclosures — which one is
+ * open, and whether closing the last is allowed — because `<details name>`
+ * alone cannot express a non-collapsible group, and gives no value to store.
+ */
+export function Accordion(props: AccordionProps) {
+  const {
+    ref,
+    value,
+    defaultValue,
+    onValueChange,
+    items,
+    children,
+    multiple = false,
+    collapsible = true,
+    variant = "separated",
+    size = "md",
+    iconPosition = "end",
+    className,
+    classNames,
+    style,
+  } = props;
+
+  const [open, setOpen] = useControllableState<string[]>(value, defaultValue ?? []);
+  const settings = useMemo(() => ({ multiple, collapsible }), [multiple, collapsible]);
+
+  /*
+   * With `items`, the panels are known and the starting value can be trimmed
+   * against them. With children they are not — and asking each item to
+   * register itself would mean either reading a ref while rendering or a
+   * second render pass on mount, for the sake of dropping a value that already
+   * matches nothing and shows nothing.
+   *
+   * The one thing that needs the list is opening a panel in a non-collapsible
+   * accordion that starts with none open, so give that case a `defaultValue`.
+   */
+  const effective = useMemo(
+    () => normalizeOpen(open, items ? items.map((item) => item.value) : open, settings),
+    [open, items, settings],
+  );
+
+  const toggle = useCallback(
+    (item: string) => {
+      const next = toggleOpen(effective, item, settings);
+      setOpen(next);
+      onValueChange?.(next);
+    },
+    [effective, settings, setOpen, onValueChange],
+  );
+
+  const context = useMemo<AccordionContextValue>(
+    () => ({ open: effective, toggle, size, variant, iconPosition }),
+    [effective, toggle, size, variant, iconPosition],
+  );
+
+  return (
+    <div
+      ref={ref}
+      className={cx("ac-root", classNames?.root, className)}
+      style={style}
+      data-variant={variant}
+      data-size={size}
+    >
+      <AccordionContext value={context}>
+        {items
+          ? items.map((item) => (
+              <AccordionItem
+                key={item.value}
+                value={item.value}
+                title={item.title}
+                description={item.description}
+                disabled={item.disabled}
+              >
+                {item.content}
+              </AccordionItem>
+            ))
+          : children}
+      </AccordionContext>
+    </div>
+  );
+}

package/source/components/accordion/react/AccordionItem.tsx

@@ -0,0 +1,120 @@
+"use client";
+
+import {
+  useId,
+  type CSSProperties,
+  type MouseEvent,
+  type ReactNode,
+  type Ref,
+} from "react";
+import { ChevronDownIcon } from "../../shared/react/icons";
+import { useAccordionContext } from "./context";
+import { cx, type AccordionItemSlot } from "./props";
+
+export interface AccordionItemProps {
+  /** Identifies the panel in the accordion's value. */
+  value: string;
+  title: ReactNode;
+  /** A second line under the title. */
+  description?: ReactNode;
+  children?: ReactNode;
+  /** Something at the end of the header: a badge, a count. */
+  meta?: ReactNode;
+  /** Replaces the chevron. */
+  icon?: ReactNode;
+  disabled?: boolean;
+  className?: string;
+  classNames?: Partial<Record<AccordionItemSlot, string>>;
+  style?: CSSProperties;
+  ref?: Ref<HTMLDetailsElement>;
+}
+
+/**
+ * One section. A `<details>` whose open state the accordion owns, so the group
+ * can close the others and refuse to close the last one.
+ */
+export function AccordionItem(props: AccordionItemProps) {
+  const {
+    ref,
+    value,
+    title,
+    description,
+    children,
+    meta,
+    icon,
+    disabled = false,
+    className,
+    classNames,
+    style,
+  } = props;
+
+  const context = useAccordionContext("AccordionItem");
+  const id = useId();
+  const open = context.open.includes(value);
+
+  const onClick = (event: MouseEvent<HTMLElement>) => {
+    // The accordion decides; letting the browser toggle as well would fight it.
+    event.preventDefault();
+    if (!disabled) context.toggle(value);
+  };
+
+  return (
+    <details
+      ref={ref}
+      className={cx("ac-item", classNames?.root, className)}
+      style={style}
+      open={open}
+      data-disabled={disabled || undefined}
+    >
+      <summary
+        id={`${id}-header`}
+        className={cx("ac-header", classNames?.header)}
+        /*
+         * An explicit button role, because a bare <summary> is exposed as a
+         * group in Chromium and `aria-expanded` on it is ignored — so the one
+         * thing a screen reader most needs to know, whether the section is
+         * open, never gets announced. The role changes nothing about the
+         * keyboard: Enter and Space still come from <details> itself.
+         */
+        role="button"
+        aria-expanded={open}
+        aria-controls={`${id}-content`}
+        // A disabled section is marked rather than removed from the tab order:
+        // the heading of something you cannot open is still worth reading, and
+        // dropping it loses it silently.
+        aria-disabled={disabled || undefined}
+        onClick={onClick}
+      >
+        {context.iconPosition === "start" && (
+          <span className={cx("ac-icon", classNames?.icon)} aria-hidden="true">
+            {icon ?? <ChevronDownIcon />}
+          </span>
+        )}
+
+        <span className="ac-heading">
+          <span className={cx("ac-title", classNames?.title)}>{title}</span>
+          {description && (
+            <span className={cx("ac-description", classNames?.description)}>{description}</span>
+          )}
+        </span>
+
+        {meta && <span className="ac-meta">{meta}</span>}
+
+        {context.iconPosition === "end" && (
+          <span className={cx("ac-icon", classNames?.icon)} aria-hidden="true">
+            {icon ?? <ChevronDownIcon />}
+          </span>
+        )}
+      </summary>
+
+      <div
+        id={`${id}-content`}
+        className={cx("ac-content", classNames?.content)}
+        role="region"
+        aria-labelledby={`${id}-header`}
+      >
+        <div className={cx("ac-body", classNames?.body)}>{children}</div>
+      </div>
+    </details>
+  );
+}

package/source/components/accordion/react/context.ts

@@ -0,0 +1,20 @@
+"use client";
+
+import { createContext, use } from "react";
+import type { AccordionIconPosition, AccordionSize, AccordionVariant } from "../core/types";
+
+export interface AccordionContextValue {
+  open: readonly string[];
+  toggle(value: string): void;
+  size: AccordionSize;
+  variant: AccordionVariant;
+  iconPosition: AccordionIconPosition;
+}
+
+export const AccordionContext = createContext<AccordionContextValue | null>(null);
+
+export function useAccordionContext(component: string): AccordionContextValue {
+  const context = use(AccordionContext);
+  if (!context) throw new Error(`<${component}> must be used inside an <Accordion>.`);
+  return context;
+}

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

@@ -0,0 +1,13 @@
+export type AccordionSlot = "root";
+
+export type AccordionItemSlot =
+  | "root"
+  | "header"
+  | "title"
+  | "description"
+  | "icon"
+  | "content"
+  | "body";
+
+// Shared with every other component, so class handling cannot drift.
+export { cx } from "../../shared/core/cx";

package/source/components/accordion/styles.css

@@ -0,0 +1,207 @@
+/*
+ * Accordion styles.
+ *
+ * Each section is a native <details>, so the marker has to be taken off (two
+ * ways: `list-item` display in Firefox, the WebKit pseudo-element elsewhere)
+ * before a chevron of our own goes on. 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.
+ */
+
+.ac-root {
+  --ac-fg: var(--gbs-fg, var(--dg-fg, light-dark(#18181b, #f4f4f5)));
+  --ac-muted: var(--gbs-muted, var(--dg-muted, light-dark(#71717a, #a1a1aa)));
+  --ac-bg: var(--gbs-bg, var(--dg-bg, light-dark(#ffffff, #0b0b0e)));
+  --ac-border: var(--gbs-border, var(--dg-border, light-dark(#e4e4e7, #27272a)));
+  --ac-hover: var(--gbs-hover, var(--dg-hover, light-dark(#f4f4f5, #1f1f23)));
+  --ac-focus: var(--gbs-focus, var(--dg-focus, light-dark(#2563eb, #60a5fa)));
+  --ac-radius: var(--gbs-radius, var(--dg-radius, 8px));
+  --ac-font-size: var(--gbs-font-size, var(--dg-font-size, 13px));
+  --ac-px: 14px;
+  --ac-py: 12px;
+  --ac-duration: 180ms;
+
+  color-scheme: inherit;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  min-width: 0;
+  font-size: var(--ac-font-size);
+  line-height: 1.5;
+  color: var(--ac-fg);
+}
+
+:where(.dark, [data-theme="dark"]) .ac-root {
+  color-scheme: dark;
+}
+:where(.light, [data-theme="light"]) .ac-root {
+  color-scheme: light;
+}
+
+:where(.ac-root) *,
+:where(.ac-root) *::before,
+:where(.ac-root) *::after {
+  box-sizing: border-box;
+}
+
+.ac-root[data-size="sm"] {
+  --ac-px: 10px;
+  --ac-py: 8px;
+  --ac-font-size: 12px;
+}
+.ac-root[data-size="lg"] {
+  --ac-px: 18px;
+  --ac-py: 16px;
+  --ac-font-size: 14px;
+}
+
+/* ---------------------------------------------------------------- item */
+
+.ac-item {
+  min-width: 0;
+  border: 1px solid var(--ac-border);
+  border-radius: var(--ac-radius);
+  background: var(--ac-bg);
+}
+
+/* Contained: one block with dividers instead of separate cards. */
+.ac-root[data-variant="contained"] {
+  gap: 0;
+  border: 1px solid var(--ac-border);
+  border-radius: var(--ac-radius);
+  overflow: hidden;
+}
+.ac-root[data-variant="contained"] .ac-item {
+  border: 0;
+  border-block-end: 1px solid var(--ac-border);
+  border-radius: 0;
+}
+.ac-root[data-variant="contained"] .ac-item:last-child {
+  border-block-end: 0;
+}
+
+/* Plain: rules only, for a sidebar or a FAQ. */
+.ac-root[data-variant="plain"] {
+  gap: 0;
+}
+.ac-root[data-variant="plain"] .ac-item {
+  border: 0;
+  border-block-end: 1px solid var(--ac-border);
+  border-radius: 0;
+  background: none;
+}
+.ac-root[data-variant="plain"] .ac-header {
+  padding-inline: 0;
+}
+.ac-root[data-variant="plain"] .ac-body {
+  padding-inline: 0;
+}
+
+/* -------------------------------------------------------------- header */
+
+.ac-header {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: var(--ac-py) var(--ac-px);
+  border-radius: inherit;
+  cursor: pointer;
+  user-select: none;
+  /* Firefox draws the triangle through `display: list-item`. */
+  list-style: none;
+}
+.ac-header::-webkit-details-marker {
+  display: none;
+}
+.ac-header:hover {
+  background: var(--ac-hover);
+}
+.ac-header:focus-visible {
+  outline: 2px solid var(--ac-focus);
+  outline-offset: -2px;
+}
+.ac-item[data-disabled] .ac-header {
+  cursor: not-allowed;
+}
+.ac-item[data-disabled] .ac-title {
+  color: var(--ac-muted);
+}
+
+.ac-heading {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  gap: 1px;
+  min-width: 0;
+}
+.ac-title {
+  font-weight: 600;
+}
+.ac-description {
+  color: var(--ac-muted);
+  font-weight: 400;
+}
+.ac-meta {
+  display: inline-flex;
+  flex: none;
+  align-items: center;
+  gap: 6px;
+  color: var(--ac-muted);
+}
+
+.ac-icon {
+  display: inline-flex;
+  flex: none;
+  color: var(--ac-muted);
+  transition: rotate var(--ac-duration) ease;
+}
+.ac-icon > svg {
+  width: 16px;
+  height: 16px;
+}
+.ac-item[open] > .ac-header .ac-icon {
+  rotate: 180deg;
+}
+
+/* ------------------------------------------------------------- content */
+
+.ac-body {
+  padding: 0 var(--ac-px) var(--ac-py);
+}
+
+/*
+ * Opening animates where the browser can do it: `interpolate-size` lets a
+ * height of `auto` be interpolated, and `::details-content` is the box to
+ * animate. Browsers without either simply show and hide, which is the
+ * behaviour everything else falls back to anyway.
+ */
+@supports (interpolate-size: allow-keywords) {
+  .ac-root {
+    interpolate-size: allow-keywords;
+  }
+  .ac-item::details-content {
+    height: 0;
+    overflow: hidden;
+    transition:
+      height var(--ac-duration) ease,
+      content-visibility var(--ac-duration) allow-discrete;
+  }
+  .ac-item[open]::details-content {
+    height: auto;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ac-root {
+    --ac-duration: 0s;
+  }
+}
+
+@media (forced-colors: active) {
+  .ac-item {
+    border: 1px solid CanvasText;
+  }
+}

package/source/components/alert/README.md

@@ -0,0 +1,39 @@
+# Alert
+
+A message that stays in the page: a trial ending, a read-only record, the
+summary above a form that failed validation. For React 19, styled to match the
+rest of the library. No runtime dependencies besides React.
+
+```ts
+import { Alert } from "@/components/alert";
+import "@/components/alert/styles.css";
+```
+
+```tsx
+<Alert variant="warning" title="Your trial ends in 3 days">
+  After that the workspace becomes read-only. <a href="/billing">Add a card</a> to keep it.
+</Alert>
+
+<Alert variant="danger" title="We could not save your changes" onDismiss={() => setShown(false)} />
+
+<Alert variant="success" size="sm">240 rows imported.</Alert>
+```
+
+**Props:** `variant` (`info` `success` `warning` `danger` `neutral`), `size`
+(`sm` `md`), `title`, `description` or `children`, `icon` (a node, or `false`),
+`actions`, `onDismiss`, `classNames` (`root` `icon` `content` `title`
+`description` `actions` `dismiss`), `localeText`, `ref`, and every `<div>`
+attribute.
+
+Which one to reach for:
+
+| | Interrupts | Lives | Use for |
+| --- | --- | --- | --- |
+| **Dialog** | Yes, blocks | Top layer | A decision that must happen now |
+| **Toast** | No, and leaves | A corner | Confirming what already happened |
+| **Alert** | No, and stays | In the layout | The state a page or section is in |
+
+`liveness(variant)` is exported from the framework-free `core`: problems get
+`role="alert"` and interrupt; everything else gets `role="status"` and waits its
+turn. An alert that was on the page from the start announces nothing either
+way, because a live region only speaks when its contents change.

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

@@ -0,0 +1,2 @@
+export { liveness, type Liveness } from "./live";
+export type * from "./types";

package/source/components/alert/core/live.ts

@@ -0,0 +1,25 @@
+import type { AlertVariant } from "./types";
+
+export interface Liveness {
+  /** `alert` interrupts whatever is being read; `status` waits its turn. */
+  role: "alert" | "status";
+  live: "assertive" | "polite";
+}
+
+/**
+ * How loudly an alert announces itself.
+ *
+ * A banner that appears after the page has loaded is news, and a screen reader
+ * has to be told whether it is worth interrupting for. Problems are:
+ * `role="alert"` cuts into whatever is being read, which is right for "your
+ * card was declined" and rude for "3 rows imported".
+ *
+ * A banner that was on the page from the start announces nothing either way —
+ * a live region only speaks when its contents change — so this only decides
+ * what happens when one appears or its text is replaced.
+ */
+export function liveness(variant: AlertVariant): Liveness {
+  return variant === "danger" || variant === "warning"
+    ? { role: "alert", live: "assertive" }
+    : { role: "status", live: "polite" };
+}

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

@@ -0,0 +1,7 @@
+export type AlertVariant = "info" | "success" | "warning" | "danger" | "neutral";
+
+export type AlertSize = "sm" | "md";
+
+export interface AlertLocaleText {
+  dismiss: string;
+}

package/source/components/alert/index.ts

@@ -0,0 +1,5 @@
+export { Alert } from "./react/Alert";
+export type { AlertProps } from "./react/Alert";
+export { defaultAlertText } from "./react/locale";
+export type { AlertSlot } from "./react/props";
+export * from "./core";