@caqophony/ui 0.3.1 → 0.5.0

package/README.md

@@ -48,11 +48,48 @@ Tailwind v4 colour/radius/z-index/opacity/duration utilities and registers the
 package's built files as a Tailwind `@source`. Override any `--token` after the
 import to re-theme.
 
-Tailwind v3 consumers: add `./node_modules/@caqophony/ui/dist/**/*.js` to
-`content` and map the same variables in `theme.extend.colors`.
+## Styles (Tailwind v3)
 
-`animate-in` / `animate-out` (used by tooltips) come from `tailwindcss-animate`
-(v3) or `tw-animate-css` (v4); without it those animations are simply absent.
+Inside the Caqophony monorepo, an app takes the Gossamer preset and adds the
+library to `content`. Do not map the tokens by hand in `theme.extend.colors`:
+that left `bg-primary-solid` with no rule, or with a rule reading a variable
+nothing declares, and neither one raises an error.
+
+```ts
+import { gossamerPreset } from '@caqophony/tokens/tailwind-preset';
+
+export default {
+  presets: [gossamerPreset],
+  darkMode: ['class'],
+  content: ['./app/**/*.{ts,tsx}', '../../packages/ui/src/**/*.{ts,tsx}'],
+};
+```
+
+The preset maps the library's tokens and declares its variables (light, and
+dark under `.dark`), and adds the utilities and the `not-first:` variant a v3
+theme cannot express. It only adds names: stock Tailwind keeps its values, your
+`theme` wins over the preset, and a variable your CSS declares wins over the
+preset's.
+
+`pnpm exec tsx scripts/check-ui-classes-compile.ts` covers the two surfaces that
+draw the library: the monorepo's product app on Tailwind v3, and a generated
+app's `globals.css` plus `styles.css` on Tailwind v4, each against the classes
+that surface can reach. It fails on a class Tailwind generates no rule for, or a
+rule reading a variable that does not reach the element by default. It runs in
+pre-push.
+
+The preset is not published. Outside the monorepo, a Tailwind v3 app needs
+`./node_modules/@caqophony/ui/dist/**/*.js` in `content` and the same mapping,
+variables, utilities and variant in its own config, or Tailwind v4 and
+`styles.css` above.
+
+## Animation and prose
+
+On Tailwind v4, `styles.css` defines the `animate-in` / `animate-out` utilities
+the modal and tooltip use, and loads `@tailwindcss/typography` for
+`MarkdownRenderer`, which `@caqophony/ui` depends on. There is nothing to add.
+On Tailwind v3, install `tailwindcss-animate` and `@tailwindcss/typography` as
+plugins.
 
 ## Use
 
@@ -60,9 +97,25 @@ Tailwind v3 consumers: add `./node_modules/@caqophony/ui/dist/**/*.js` to
 import { Button, Card, PageContent } from '@caqophony/ui';
 import { BarChart } from '@caqophony/ui/charts';
 import { MarkdownRenderer } from '@caqophony/ui/markdown';
+import { MarketingCta, MarketingFooter } from '@caqophony/ui/marketing';
+import { Band, Display, Stack, Text } from '@caqophony/ui/material';
 ```
 
-Every entry point carries a `'use client'` directive.
+`@caqophony/ui/material` holds what a designed page is composed from: bands,
+display type, layout, and flat illustration pieces. Each colour is a token, so a
+theme change reaches all of it. Set a `Band`'s `surface` to `night` and every
+library component inside reads on the dark ground, with no prop of its own.
+
+`@caqophony/ui/material-tones` holds `FILL` and `STROKE`, the classes art draws
+in. It and `@caqophony/ui/material-art` are the entries with no `'use client'`
+directive, so a server component can use them. Every other entry point carries
+the directive.
+
+An app's own art is data, not code: a closed tree of SVG elements in tones, in a
+`*.art.json` file in `art/` beside `app/`, outside the library. `Art` from
+`@caqophony/ui/material-art` draws it, as a `Figure`'s one child, and nothing else
+makes elements in the slot. Shade `paper` with a held step at low opacity: `paper`
+keeps its colour in dark mode and `mist-*` does not.
 
 ## Licence
 

package/dist/chunk-44GEHNZP.js

@@ -0,0 +1,126 @@
+'use client';
+import {
+  Icon
+} from "./chunk-ID7VBGJA.js";
+import {
+  cn
+} from "./chunk-DP5WQAPO.js";
+
+// src/empty-value.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var EMPTY_VALUE_GLYPH = "\u2014";
+function isEmptyValue(value) {
+  return value === null || value === void 0 || value === false || typeof value === "string" && value.trim() === "";
+}
+function EmptyValue({ className }) {
+  return /* @__PURE__ */ jsxs("span", { "data-empty-value": true, className: cn("text-muted-foreground", className), children: [
+    /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: EMPTY_VALUE_GLYPH }),
+    /* @__PURE__ */ jsx("span", { className: "sr-only", children: "Not set" })
+  ] });
+}
+
+// src/alert.tsx
+import * as React from "react";
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var INTENT_SUBTLE_STYLES = {
+  success: "bg-intent-success/10 text-intent-success-foreground border-intent-success/20",
+  warning: "bg-intent-warning/10 text-intent-warning-foreground border-intent-warning/20",
+  error: "bg-intent-error/10 text-intent-error-foreground border-intent-error/20",
+  info: "bg-intent-info/10 text-intent-info-foreground border-intent-info/20"
+};
+var SOLID_STYLES = {
+  success: "border-transparent bg-intent-success-solid text-intent-success-solid-fg",
+  warning: "border-transparent bg-intent-warning-solid text-intent-warning-solid-fg",
+  error: "border-transparent bg-intent-error-solid text-intent-error-solid-fg",
+  info: "border-transparent bg-intent-info-solid text-intent-info-solid-fg"
+};
+var OUTLINE_STYLES = {
+  success: "border-intent-success-border text-intent-success-foreground bg-background",
+  warning: "border-intent-warning-border text-intent-warning-foreground bg-background",
+  error: "border-intent-error-border text-intent-error-foreground bg-background",
+  info: "border-intent-info-border text-intent-info-foreground bg-background"
+};
+var ICON_MAP = {
+  success: "circle-check",
+  warning: "triangle-alert",
+  error: "circle-alert",
+  info: "info"
+};
+var Alert = React.forwardRef(
+  ({
+    className,
+    intent = "info",
+    variant = "subtle",
+    title,
+    dismissible,
+    onDismiss,
+    children,
+    ...props
+  }, ref) => {
+    const styles = variant === "solid" ? SOLID_STYLES[intent] : variant === "outline" ? OUTLINE_STYLES[intent] : INTENT_SUBTLE_STYLES[intent];
+    return /* @__PURE__ */ jsxs2(
+      "div",
+      {
+        ref,
+        role: "alert",
+        className: cn("flex gap-3 rounded-lg border p-4", styles, className),
+        ...props,
+        children: [
+          /* @__PURE__ */ jsx2("span", { className: "flex-shrink-0 pt-0.5", "aria-hidden": "true", children: /* @__PURE__ */ jsx2(Icon, { name: ICON_MAP[intent], size: "md" }) }),
+          /* @__PURE__ */ jsxs2("div", { className: "min-w-0 flex-1", children: [
+            title && /* @__PURE__ */ jsx2("p", { className: "font-semibold", children: title }),
+            children && /* @__PURE__ */ jsx2("div", { className: cn(title && "mt-1", "text-sm"), children })
+          ] }),
+          dismissible && /* @__PURE__ */ jsx2(
+            "button",
+            {
+              type: "button",
+              onClick: onDismiss,
+              className: "flex-shrink-0 hover:opacity-80",
+              "aria-label": "Dismiss",
+              children: "\u2715"
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+Alert.displayName = "Alert";
+
+// src/intent-badge.tsx
+import * as React2 from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var INTENT_CLASSES = {
+  neutral: "bg-muted text-muted-foreground border-border",
+  // the primary tint is lighter than the intents': `primary-text` on a 10%
+  // tint over the page grey drew 4.46:1 (W1 sheet), under AA
+  primary: "bg-primary/5 text-primary-text border-primary/30",
+  ...INTENT_SUBTLE_STYLES
+};
+var IntentBadge = React2.forwardRef(
+  ({ className, intent = "neutral", children, ...props }, ref) => /* @__PURE__ */ jsx3(
+    "span",
+    {
+      ref,
+      title: typeof children === "string" ? children : void 0,
+      className: cn(
+        "inline-flex max-w-full items-center rounded-full border px-2.5 py-0.5 text-xs font-medium",
+        INTENT_CLASSES[intent],
+        className
+      ),
+      ...props,
+      children: /* @__PURE__ */ jsx3("span", { className: "truncate", children: isEmptyValue(children) ? /* @__PURE__ */ jsx3(EmptyValue, {}) : children })
+    }
+  )
+);
+IntentBadge.displayName = "IntentBadge";
+
+export {
+  EMPTY_VALUE_GLYPH,
+  isEmptyValue,
+  EmptyValue,
+  INTENT_SUBTLE_STYLES,
+  Alert,
+  IntentBadge
+};

package/dist/chunk-DP5WQAPO.js

@@ -0,0 +1,23 @@
+'use client';
+
+// src/utils.ts
+import { clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+var merge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [
+        {
+          text: ["display-poster", "display-headline", "display-title", "lede"]
+        }
+      ]
+    }
+  }
+});
+function cn(...inputs) {
+  return merge(clsx(inputs));
+}
+
+export {
+  cn
+};

package/dist/chunk-I5DQCG6D.js

@@ -0,0 +1,378 @@
+'use client';
+import {
+  CONTENT_GUTTER,
+  Icon
+} from "./chunk-ID7VBGJA.js";
+import {
+  cn
+} from "./chunk-DP5WQAPO.js";
+
+// src/spinner.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function Spinner(props) {
+  const { size = "md", className } = props;
+  const glyph = /* @__PURE__ */ jsx(Icon, { name: "loader", size, className: "animate-spin" });
+  if (props.decorative)
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        "aria-hidden": "true",
+        className: cn("inline-flex shrink-0 text-current", className),
+        children: glyph
+      }
+    );
+  return /* @__PURE__ */ jsxs(
+    "span",
+    {
+      role: "status",
+      className: cn("inline-flex shrink-0 text-current", className),
+      children: [
+        glyph,
+        /* @__PURE__ */ jsx("span", { className: "sr-only", children: props.label })
+      ]
+    }
+  );
+}
+
+// src/button.tsx
+import { Slot } from "@radix-ui/react-slot";
+import { cva } from "class-variance-authority";
+import * as React from "react";
+import { Fragment, jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+var buttonVariants = cva(
+  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary-solid text-primary-foreground shadow hover:bg-[color:color-mix(in_oklab,hsl(var(--primary-solid))_85%,black)]",
+        destructive: "bg-intent-error-solid text-intent-error-solid-fg shadow-sm hover:bg-[color:color-mix(in_oklab,hsl(var(--intent-error-solid))_85%,black)]",
+        outline: "border border-border dark:border-border bg-background dark:bg-background text-foreground dark:text-foreground shadow-sm hover:bg-muted dark:hover:bg-muted hover:text-foreground dark:hover:text-foreground",
+        secondary: "bg-muted dark:bg-muted text-muted-foreground dark:text-muted-foreground shadow-sm hover:bg-muted/80 dark:hover:bg-muted/80",
+        ghost: "hover:bg-muted dark:hover:bg-muted hover:text-foreground dark:hover:text-foreground",
+        link: "text-primary-text dark:text-primary-text underline-offset-4 hover:underline"
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "size-10"
+      }
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default"
+    }
+  }
+);
+var Button = React.forwardRef(
+  ({
+    className,
+    variant,
+    size,
+    asChild = false,
+    loading = false,
+    loadingText,
+    children,
+    disabled,
+    ...props
+  }, ref) => {
+    const Comp = asChild && !loading ? Slot : "button";
+    const isDisabled = disabled || loading;
+    return /* @__PURE__ */ jsx2(
+      Comp,
+      {
+        className: cn(buttonVariants({ variant, size, className })),
+        ref,
+        disabled: isDisabled,
+        "aria-busy": loading,
+        ...props,
+        children: loading ? /* @__PURE__ */ jsxs2(Fragment, { children: [
+          /* @__PURE__ */ jsx2(Spinner, { decorative: true, size: "sm" }),
+          /* @__PURE__ */ jsx2("span", { children: loadingText || children })
+        ] }) : children
+      }
+    );
+  }
+);
+Button.displayName = "Button";
+
+// src/container.tsx
+import * as React2 from "react";
+import { jsx as jsx3 } from "react/jsx-runtime";
+var SIZE_CLASSES = {
+  sm: "max-w-content-sm",
+  md: "max-w-content-md",
+  lg: "max-w-content-lg",
+  xl: "max-w-content-xl",
+  full: "max-w-full"
+};
+var Container = React2.forwardRef(
+  ({ className, size = "xl", padded = true, ...props }, ref) => /* @__PURE__ */ jsx3(
+    "div",
+    {
+      ref,
+      className: cn(
+        "mx-auto w-full",
+        SIZE_CLASSES[size],
+        padded && CONTENT_GUTTER,
+        className
+      ),
+      ...props
+    }
+  )
+);
+Container.displayName = "Container";
+
+// src/modal-surface.ts
+import * as React3 from "react";
+import { createPortal } from "react-dom";
+var TABBABLE = "a[href], button:not(:disabled), input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]";
+var neverChanges = () => () => void 0;
+var tabStops = (panel) => [...panel.querySelectorAll(TABBABLE)].filter(
+  (el) => el.tabIndex >= 0 && el.getClientRects().length > 0 && getComputedStyle(el).visibility === "visible"
+);
+function holdFocus(panel) {
+  if (!panel.hasAttribute("tabindex")) panel.tabIndex = -1;
+  panel.focus();
+}
+var surfaces = [];
+function onKey(e) {
+  const top = surfaces[surfaces.length - 1];
+  const box = top?.panel.current;
+  if (!top || !box) return;
+  const at = document.activeElement;
+  if (at && !box.contains(at) && box.compareDocumentPosition(at) & Node.DOCUMENT_POSITION_FOLLOWING)
+    return;
+  if (e.key === "Escape" && !e.defaultPrevented) top.escape.current?.();
+  if (e.key !== "Tab") return;
+  const stops = tabStops(box);
+  const first = stops[0];
+  const last = stops[stops.length - 1];
+  if (!first || !last) {
+    e.preventDefault();
+    holdFocus(box);
+    return;
+  }
+  const inside = box.contains(at);
+  if (e.shiftKey && (at === first || !inside)) {
+    e.preventDefault();
+    last.focus();
+  } else if (!e.shiftKey && (at === last || !inside)) {
+    e.preventDefault();
+    first.focus();
+  }
+}
+function enter(surface) {
+  if (surfaces.length === 0) document.addEventListener("keydown", onKey);
+  surfaces.push(surface);
+  return () => {
+    surfaces.splice(surfaces.indexOf(surface), 1);
+    if (surfaces.length === 0) document.removeEventListener("keydown", onKey);
+  };
+}
+function usePanelRef(forwarded) {
+  const panel = React3.useRef(null);
+  const setPanel = React3.useCallback(
+    (el) => {
+      panel.current = el;
+      if (typeof forwarded === "function") forwarded(el);
+      else if (forwarded) forwarded.current = el;
+    },
+    [forwarded]
+  );
+  return [panel, setPanel];
+}
+function useModalSurface(open, panel, onEscape) {
+  const hydrated = React3.useSyncExternalStore(
+    neverChanges,
+    () => true,
+    () => false
+  );
+  const escape = React3.useRef(onEscape);
+  React3.useEffect(() => {
+    escape.current = onEscape;
+  });
+  const active = open && hydrated;
+  const opener = React3.useRef(null);
+  React3.useInsertionEffect(() => {
+    if (active) opener.current = document.activeElement;
+  }, [active]);
+  React3.useEffect(() => {
+    const box = panel.current;
+    if (!active || !box) return;
+    if (!box.contains(document.activeElement)) {
+      const first = tabStops(box)[0];
+      if (first) first.focus();
+      else holdFocus(box);
+    }
+    const leave = enter({ panel, escape });
+    return () => {
+      leave();
+      const nowhere = !document.activeElement || document.activeElement === document.body;
+      const back = opener.current;
+      if (nowhere && back instanceof HTMLElement) back.focus();
+    };
+  }, [active, panel]);
+  return (surface) => hydrated ? createPortal(surface, document.body) : surface;
+}
+
+// src/nav-drawer.tsx
+import * as React4 from "react";
+import { Fragment as Fragment2, jsx as jsx4, jsxs as jsxs3 } from "react/jsx-runtime";
+function NavDrawer({
+  label,
+  side,
+  closedFrom,
+  defaultOpen,
+  children,
+  triggerClassName,
+  surface
+}) {
+  const [open, setOpen] = React4.useState(defaultOpen);
+  const id = React4.useId();
+  const menuButton = React4.useRef(null);
+  const overlay = React4.useRef(null);
+  const panel = React4.useRef(null);
+  const close = React4.useCallback(() => {
+    setOpen(false);
+    menuButton.current?.focus();
+  }, []);
+  const place = useModalSurface(open, panel, close);
+  React4.useEffect(() => {
+    if (!open) return;
+    const onClick = (e) => {
+      const el = panel.current;
+      if (el && e.composedPath().includes(el) && e.target instanceof Element && e.target.closest("a"))
+        close();
+    };
+    document.addEventListener("click", onClick);
+    return () => document.removeEventListener("click", onClick);
+  }, [open, close]);
+  React4.useEffect(() => {
+    if (!open || closedFrom === null) return;
+    const onResize = () => {
+      if (overlay.current && getComputedStyle(overlay.current).display === "none")
+        setOpen(false);
+    };
+    onResize();
+    window.addEventListener("resize", onResize);
+    return () => window.removeEventListener("resize", onResize);
+  }, [open, closedFrom]);
+  const left = side === "left";
+  const drawer = open ? /* @__PURE__ */ jsxs3(
+    "div",
+    {
+      ref: overlay,
+      className: cn(
+        "z-overlay fixed inset-0",
+        closedFrom === "md" && "md:hidden",
+        closedFrom === "lg" && "lg:hidden"
+      ),
+      children: [
+        /* @__PURE__ */ jsx4(
+          "div",
+          {
+            "aria-hidden": "true",
+            className: "absolute inset-0 bg-foreground/40",
+            onClick: close
+          }
+        ),
+        /* @__PURE__ */ jsxs3(
+          "div",
+          {
+            ref: panel,
+            id,
+            role: "dialog",
+            "aria-modal": "true",
+            "aria-label": label,
+            "data-surface": surface,
+            className: cn(
+              "absolute inset-y-0 flex w-72 max-w-[calc(100%-3rem)] flex-col overflow-y-auto bg-card shadow-lg",
+              left ? "left-0 border-r" : "right-0 border-l",
+              "border-border"
+            ),
+            children: [
+              /* @__PURE__ */ jsx4(
+                "div",
+                {
+                  className: cn(
+                    "flex px-2 py-2",
+                    left ? "justify-end" : "justify-start"
+                  ),
+                  children: /* @__PURE__ */ jsx4(
+                    Button,
+                    {
+                      variant: "ghost",
+                      size: "icon",
+                      "aria-label": "Close",
+                      onClick: close,
+                      children: /* @__PURE__ */ jsx4(Icon, { name: "x", size: "sm" })
+                    }
+                  )
+                }
+              ),
+              children
+            ]
+          }
+        )
+      ]
+    }
+  ) : null;
+  return /* @__PURE__ */ jsxs3(Fragment2, { children: [
+    /* @__PURE__ */ jsx4(
+      Button,
+      {
+        ref: menuButton,
+        variant: "ghost",
+        size: "icon",
+        "aria-label": label,
+        "aria-expanded": open,
+        "aria-controls": open ? id : void 0,
+        className: triggerClassName,
+        onClick: () => setOpen(!open),
+        children: /* @__PURE__ */ jsx4(Icon, { name: "menu", size: "sm" })
+      }
+    ),
+    drawer && place(drawer)
+  ] });
+}
+
+// src/navbar-menu.tsx
+import { jsx as jsx5, jsxs as jsxs4 } from "react/jsx-runtime";
+function NavbarMenu({
+  search,
+  links,
+  actions,
+  defaultOpen = false,
+  triggerClassName,
+  folded = false,
+  surface
+}) {
+  return /* @__PURE__ */ jsx5("div", { className: folded ? "ml-auto" : "ml-auto md:hidden", children: /* @__PURE__ */ jsxs4(
+    NavDrawer,
+    {
+      label: "Navigation",
+      side: "right",
+      closedFrom: folded ? null : "md",
+      defaultOpen,
+      triggerClassName,
+      surface,
+      children: [
+        search && /* @__PURE__ */ jsx5("div", { className: "px-4 pb-3", children: search }),
+        links && /* @__PURE__ */ jsx5("nav", { className: "flex flex-col px-4 pb-3 [&>a]:whitespace-normal [&>a]:py-2.5 [&>a]:text-base", children: links }),
+        actions && /* @__PURE__ */ jsx5("div", { className: "flex flex-col gap-2 border-t border-border p-4 [&>*]:w-full", children: actions })
+      ]
+    }
+  ) });
+}
+
+export {
+  Spinner,
+  buttonVariants,
+  Button,
+  usePanelRef,
+  useModalSurface,
+  NavDrawer,
+  NavbarMenu,
+  Container
+};