@charcuterie/ui 2.6.0 → 2.8.0

package/src/controlStyles.ts

@@ -16,7 +16,18 @@
  * `packages/tokens/src/tailwindCollisions.test.ts`.
  */
 
-import type { ControlSize } from "@charcuterie/tokens"
+import type {
+  ControlSize,
+  IntentName,
+} from "@charcuterie/tokens"
+
+import type { IntentAppearance } from "./intentStyles.ts"
+import {
+  FOCUS_RING_CLASS,
+  INTENT_APPEARANCE_CLASS,
+  INTENT_HOVER_CLASS,
+} from "./intentStyles.ts"
+import { toClassName } from "./toClassName.ts"
 
 export const CONTROL_SIZE_CLASS: Record<
   ControlSize,
@@ -58,6 +69,63 @@ export const ICON_CONTROL_SIZE_CLASS: Record<
 export const MIN_TOUCH_TARGET_CLASS =
   "min-h-(--control-min-touch-target) min-w-(--control-min-touch-target)"
 
+/**
+ * Everything a pressable control looks like before an intent, a size,
+ * or a state is applied to it.
+ *
+ * Pulled out of `Button` the day `ButtonLink` shipped. Those two must
+ * paint **identically** — the whole point of `ButtonLink` is that a
+ * navigation can read as a primary button — and "identically" spelled
+ * as two copies of the same string is a promise that survives exactly
+ * one edit.
+ */
+export const CONTROL_BASE_CLASS =
+  "inline-flex cursor-pointer items-center justify-center rounded-md border font-medium whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard select-none"
+
+/**
+ * The one class list a button-shaped control wears, assembled once.
+ *
+ * `Button` and `ButtonLink` call this with the same arguments and get
+ * the same string back, so a new appearance, a changed radius, or a
+ * different hover ramp reaches both or neither. `ButtonLink.test.tsx`
+ * asserts the resulting *computed styles* match, which is the version
+ * of this claim a class-name refactor cannot quietly break.
+ *
+ * The disabled treatment is the caller's, because it is the one thing
+ * that genuinely differs: a `<button>` has a real `disabled`
+ * attribute and gets `DISABLED_CLASS`, while an `<a>` has no such
+ * concept and gets `ARIA_DISABLED_CLASS` keyed off `aria-disabled`.
+ */
+export const getControlClassName = ({
+  appearance,
+  className,
+  disabledClass,
+  intent,
+  isFullWidth,
+  size,
+  sizing,
+}: {
+  appearance: IntentAppearance
+  className?: string
+  disabledClass: string
+  intent: IntentName
+  isFullWidth: boolean
+  size: ControlSize
+  sizing: "control" | "icon"
+}): string =>
+  toClassName(
+    CONTROL_BASE_CLASS,
+    sizing === "icon"
+      ? ICON_CONTROL_SIZE_CLASS[size]
+      : CONTROL_SIZE_CLASS[size],
+    INTENT_APPEARANCE_CLASS[intent][appearance],
+    INTENT_HOVER_CLASS[intent][appearance],
+    FOCUS_RING_CLASS,
+    disabledClass,
+    isFullWidth && "w-full",
+    className,
+  )
+
 /**
  * Non-control sizing: badges, indicator dots, spinners. These are
  * type-relative on purpose — a badge beside `text-sm` prose that

package/src/icons.storyHelpers.tsx

@@ -48,6 +48,38 @@ export const SettingsIcon = (): ReactNode => (
   </svg>
 )
 
+/**
+ * The back-arrow seven repos spell as a literal `←`, drawn instead —
+ * so the `TextLink` boards screenshot as an arrow rather than as the
+ * blank box that character measures in this Chromium.
+ */
+export const ArrowLeftIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M19 12H5" />
+
+    <path d="m11 18-6-6 6-6" />
+  </svg>
+)
+
+export const ArrowRightIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M5 12h14" />
+
+    <path d="m13 6 6 6-6 6" />
+  </svg>
+)
+
+/** The `↗` an app puts after an external link, drawn. */
+export const ExternalIcon = (): ReactNode => (
+  <svg {...iconProps} aria-hidden="true">
+    <path d="M14 5h5v5" />
+
+    <path d="M19 5 10 14" />
+
+    <path d="M18 14v4a1 1 0 0 1-1 1H6a1 1 0 0 1-1-1V7a1 1 0 0 1 1-1h4" />
+  </svg>
+)
+
 export const UndoIcon = (): ReactNode => (
   <svg {...iconProps} aria-hidden="true">
     <path d="M9 14 4 9l5-5" />

package/src/index.ts

@@ -37,6 +37,27 @@ export type {
   AccordionProps,
 } from "./Accordion/Accordion.tsx"
 export { Accordion } from "./Accordion/Accordion.tsx"
+export type { AdaptiveGridProps } from "./AdaptiveGrid/AdaptiveGrid.tsx"
+export { AdaptiveGrid } from "./AdaptiveGrid/AdaptiveGrid.tsx"
+export type { ColumnChoice } from "./AdaptiveGrid/chooseColumns.ts"
+export {
+  chooseColumns,
+  DEFAULT_MAX_AUTO_COLUMNS,
+  DEFAULT_MAX_MANUAL_COLUMNS,
+  DEFAULT_MIN_COLUMN_INLINE_SIZE_PX,
+  getColumnChoices,
+  getContentMaxInlineSize,
+} from "./AdaptiveGrid/chooseColumns.ts"
+export type {
+  BlockSizeResolver,
+  ColumnPersistence,
+} from "./AdaptiveGrid/useAdaptiveColumns.ts"
+export {
+  localStorageColumnPersistence,
+  readStoredChoice,
+  useAdaptiveColumns,
+  viewportBlockSizeResolver,
+} from "./AdaptiveGrid/useAdaptiveColumns.ts"
 export type {
   AlertProps,
   AlertSize,
@@ -46,6 +67,8 @@ export type { BadgeProps } from "./Badge/Badge.tsx"
 export { Badge } from "./Badge/Badge.tsx"
 export type { ButtonProps } from "./Button/Button.tsx"
 export { Button } from "./Button/Button.tsx"
+export type { ButtonLinkProps } from "./ButtonLink/ButtonLink.tsx"
+export { ButtonLink } from "./ButtonLink/ButtonLink.tsx"
 export type {
   CardPadding,
   CardProps,
@@ -66,8 +89,10 @@ export { Combobox } from "./Combobox/Combobox.tsx"
 export type { BadgeSize } from "./controlStyles.ts"
 export {
   BADGE_SIZE_CLASS,
+  CONTROL_BASE_CLASS,
   CONTROL_SIZE_CLASS,
   DOT_SIZE_CLASS,
+  getControlClassName,
   ICON_CONTROL_SIZE_CLASS,
   MIN_TOUCH_TARGET_CLASS,
   SPINNER_SIZE_CLASS,
@@ -92,6 +117,7 @@ export type { IconButtonProps } from "./IconButton/IconButton.tsx"
 export { IconButton } from "./IconButton/IconButton.tsx"
 export type { IntentAppearance } from "./intentStyles.ts"
 export {
+  ARIA_DISABLED_CLASS,
   DISABLED_CLASS,
   FOCUS_RING_CLASS,
   INTENT_APPEARANCE_CLASS,
@@ -148,6 +174,16 @@ export type {
   RadioItem,
 } from "./RadioGroup/RadioGroup.tsx"
 export { RadioGroup } from "./RadioGroup/RadioGroup.tsx"
+export { AnchorLink } from "./RouterLink/AnchorLink.tsx"
+export {
+  RouterLinkProvider,
+  useRouterLink,
+} from "./RouterLink/RouterLinkProvider.tsx"
+export type {
+  RouterLinkComponent,
+  RouterLinkProps,
+} from "./RouterLink/routerLink.ts"
+export { getIsRoutedHref } from "./RouterLink/routerLink.ts"
 export type {
   SegmentedControlProps,
   SegmentedItem,
@@ -196,6 +232,11 @@ export type {
   TabsProps,
 } from "./Tabs/Tabs.tsx"
 export { Tabs } from "./Tabs/Tabs.tsx"
+export type {
+  TextLinkAppearance,
+  TextLinkProps,
+} from "./TextLink/TextLink.tsx"
+export { TextLink } from "./TextLink/TextLink.tsx"
 export type { ToastProps } from "./Toast/Toast.tsx"
 export { Toast } from "./Toast/Toast.tsx"
 export type {

package/src/intentStyles.ts

@@ -205,3 +205,22 @@ export const FOCUS_RING_CLASS =
  */
 export const DISABLED_CLASS =
   "disabled:cursor-not-allowed disabled:border-border-subtle disabled:bg-surface-sunken disabled:text-content-disabled disabled:shadow-none"
+
+/**
+ * The same treatment for something that cannot *be* disabled.
+ *
+ * **`disabled` is not a thing an `<a>` has.** There is no attribute,
+ * no `:disabled` match, and no browser behaviour to inherit — so a
+ * "disabled link" is entirely something a component has to build, and
+ * the usual build of it is a focusable `<a href>` that silently does
+ * nothing when pressed. `ButtonLink` instead drops `href` (the
+ * platform's own way to make an anchor inert and unfocusable) and
+ * says so with `aria-disabled`, which is what this paints against.
+ *
+ * `pointer-events-none` rather than `cursor-not-allowed`: without a
+ * real `:disabled`, the `hover:` classes still match — CSS `:hover`
+ * fires on disabled elements too — so the hover fill has to be taken
+ * off the table rather than merely overridden.
+ */
+export const ARIA_DISABLED_CLASS =
+  "aria-disabled:pointer-events-none aria-disabled:border-border-subtle aria-disabled:bg-surface-sunken aria-disabled:text-content-disabled aria-disabled:shadow-none"

package/src/reactRouter/ReactRouterLink.tsx

@@ -0,0 +1,30 @@
+import type { ReactNode } from "react"
+import { Link } from "react-router"
+
+import type { RouterLinkProps } from "../RouterLink/routerLink.ts"
+
+/**
+ * react-router's `<Link>`, wearing the seam's `href`.
+ *
+ * The entire adapter, and that is the point: the seam's contract is
+ * "a component that takes `href`", so an adapter is a rename. wouter,
+ * TanStack Router, and a hand-rolled router each get the same four
+ * lines, written in the app rather than here.
+ *
+ * `to` versus `href` is the only mismatch worth naming. Everything
+ * else — `className`, `rel`, `target`, `aria-*`, the ref — passes
+ * through untouched, because react-router renders a real `<a>` and
+ * forwards what it does not understand.
+ *
+ * Imported from `react-router`, not `react-router-dom`. v7 and v8
+ * both export `Link` from the former, and `react-router-dom` v7 (what
+ * bambuddy has) is a re-export shim over exactly that module — so one
+ * import covers both installs, while naming `react-router-dom` would
+ * cover only one.
+ */
+export const ReactRouterLink = ({
+  href,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <Link {...linkProps} to={href} />
+)

package/src/reactRouter/index.ts

@@ -0,0 +1,29 @@
+/**
+ * `@charcuterie/ui/react-router` — the react-router adapter for the
+ * link seam.
+ *
+ * **A subpath export with an optional peer dependency**, and both
+ * halves of that matter. The base package must stay router-free: the
+ * fleet runs react-router v8, react-router-dom v7, wouter-preact, two
+ * hand-rolled routers, and five apps with no router at all, so a
+ * `react-router` in `@charcuterie/ui`'s dependencies would be a
+ * package eleven consumers install and six of them use. Optional
+ * peer + separate entry point means an app that never imports this
+ * path never resolves `react-router`, and `sourceRules.test.ts`
+ * asserts exactly that — the main entry is measured for what it
+ * reaches, so this cannot leak into it by accident.
+ *
+ * The wiring is one provider at the app root; `Guides/Routing` in
+ * Storybook is the copy-pasteable version.
+ *
+ * ```tsx
+ * import { RouterLinkProvider } from "@charcuterie/ui"
+ * import { ReactRouterLink } from "@charcuterie/ui/react-router"
+ *
+ * <RouterLinkProvider link={ReactRouterLink}>
+ *   <RouterProvider router={router} />
+ * </RouterLinkProvider>
+ * ```
+ */
+
+export { ReactRouterLink } from "./ReactRouterLink.tsx"

package/src/sourceRules.test.ts

@@ -240,13 +240,22 @@ test("the barrel is the only place components are re-exported", async () => {
   // sibling *through* `index.ts` turns every component into a
   // dependency of every other one, which is how a 3 KB `Spinner`
   // starts pulling in `MediaTile`.
+  //
+  // Comments are stripped first, for the same reason the colour rule
+  // strips them: a docstring showing a *consumer* how to wire
+  // `RouterLinkProvider` has to spell `from "@charcuterie/ui"`, and a
+  // rule that cannot tell a citation from an import is a rule that
+  // gets switched off. An actual import is never inside a comment.
   const offenders = componentFiles
     .filter((one) => one.file !== "index.ts")
-    .filter(
-      (one) =>
-        /from "\.\.?\/index\.ts"/.test(one.contents) ||
-        /from "@charcuterie\/ui"/.test(one.contents),
-    )
+    .filter((one) => {
+      const code = stripComments(one.contents)
+
+      return (
+        /from "\.\.?\/index\.ts"/.test(code) ||
+        /from "@charcuterie\/ui"/.test(code)
+      )
+    })
     .map((one) => one.file)
 
   expect(offenders).toEqual([])
@@ -313,7 +322,27 @@ test("the barrel is the only place components are re-exported", async () => {
   // because both registrations are effects — and stays out of this
   // count and the barrel by the `<Name>/<Name>.tsx` rule, exactly as
   // `SegmentedOption` does.
-  expect(componentNames.length).toBe(35)
+  //
+  // `AdaptiveGrid` is the library's first *layout* component, and the
+  // first one whose reason to exist is a rule rather than a widget:
+  // the wrapping grids in this fleet are `auto-fill, minmax()`, which
+  // takes every column the window allows and lands on seven items
+  // strung across an ultrawide. It spends height first instead, and
+  // it is a component rather than only a hook because three things
+  // about the markup are silent when they are wrong — the
+  // measured box must not be the capped box, `min-w-0` has to reach
+  // children the caller owns, and the track list must be an inline
+  // style because Tailwind cannot scan an interpolated class: +1 -> 36.
+  // The link family closes the gap that made seven repos hand-roll a
+  // back-link and made `Button` get used for navigation: `TextLink`
+  // and `ButtonLink`, both a real `<a href>`, differing in paint
+  // rather than semantics: +2 -> 38, on top of `AdaptiveGrid`'s 36.
+  // `AnchorLink`,
+  // `RouterLinkProvider`, and `ReactRouterLink` are the seam rather
+  // than components anybody stories, and live in `RouterLink/` and
+  // `reactRouter/` — outside this count by the `<Name>/<Name>.tsx`
+  // rule, exactly as `Overlay/`'s parts are.
+  expect(componentNames.length).toBe(38)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)
@@ -418,6 +447,12 @@ const ENTRY_POINT_RUNTIMES: Record<
       "@tanstack/react-virtual",
       "react",
     ],
+    // The router seam's one shipped adapter, and the reason it is a
+    // subpath rather than part of the barrel: `react-router` appears
+    // **only** here, as an optional peer, so the eleven consumers of
+    // the main entry never resolve it. Six of them do not have a
+    // react-router at all.
+    "./react-router": ["react", "react-router"],
     "./testing": [],
     "./tokens": ["@charcuterie/tokens"],
   },

package/src/styles.css

@@ -1,14 +1,19 @@
-/* `@charcuterie/ui/styles.css` — the four looping affordances, and
- * nothing else.
+/* `@charcuterie/ui/styles.css` — the four looping affordances and
+ * the token-tinted scrollbar: the visuals a Tailwind utility cannot
+ * express against our tokens, and nothing else.
  *
  * Every other visual in this package is a Tailwind utility reading
  * a token, which is what makes a scheme/density/variant flip a
- * repaint with no re-render. Animation is the one thing utilities
- * cannot express against our tokens: Tailwind's own `animate-spin`
- * and `animate-pulse` hardcode 1s and 2s, ignore
- * `prefers-reduced-motion`, and are therefore beyond the theme's
- * reach — which is exactly why `MotionTokens` carries a separate
- * `loopFast`/`loopSlow` ramp.
+ * repaint with no re-render. Two things sit outside that reach.
+ * Animation is one: Tailwind's own `animate-spin` and `animate-pulse`
+ * hardcode 1s and 2s, ignore `prefers-reduced-motion`, and are
+ * therefore beyond the theme's reach — which is exactly why
+ * `MotionTokens` carries a separate `loopFast`/`loopSlow` ramp. The
+ * scrollbar is the other: the `::-webkit-scrollbar` pseudo-elements
+ * (and Firefox's `scrollbar-width`/`scrollbar-color`) have no
+ * `@theme`-generated utility, so `.charcuterie-scrollbar` at the foot
+ * of this file reads the same `--color-*` roles by hand and flips with
+ * `data-scheme` on the same repaint as everything else.
  *
  * Consumers import this once, after `@charcuterie/tokens/theme.css`.
  *
@@ -128,3 +133,78 @@
     );
   }
 }
+
+/* `.charcuterie-scrollbar` — a token-tinted scrollbar for any element
+ * that scrolls. The fleet grew this twice by hand (gallery-downloader's
+ * `scrollbar-thin-token`, image-viewer's global `::-webkit-scrollbar`
+ * block); this is the one copy, promoted here so a scheme flip
+ * repaints it for free.
+ *
+ * The *designed* look is the `::-webkit-scrollbar` path: a 12px bar, a
+ * rounded thumb, a track-coloured inset, no step arrows. That is what
+ * Chromium, Edge, and Safari paint. Chromium 121+ will *prefer*
+ * `scrollbar-width` / `scrollbar-color` over these pseudo-elements
+ * whenever both are set, which collapses the bar to the thin OS chrome
+ * (arrows and all on Windows) — so the standard properties are scoped
+ * to Firefox only, where `::-webkit-scrollbar` never runs.
+ *
+ * Firefox gets the closest standard-property match (thin, token-tinted
+ * thumb, transparent track). It cannot round a corner or draw a track
+ * inset — a platform limit, not an omission here.
+ *
+ * `::-webkit-scrollbar-button` is suppressed deliberately: the
+ * affordance is the thumb on a track, not step arrows.
+ *
+ * Both engines read the same three roles — `border-strong` for the
+ * thumb, `surface-sunken` for the track, `content-muted` for the thumb
+ * on hover — so the bar is themed by `[data-scheme]` on `<html>` with
+ * nothing in React observing it. `width`/`height` rather than a
+ * logical property is not a lapse: the `::-webkit-scrollbar`
+ * pseudo-elements size only by the physical pair, and a vertical bar's
+ * thickness is its `width` regardless of writing direction. */
+
+/* The designed bar — Chromium, Edge, Safari. */
+.charcuterie-scrollbar::-webkit-scrollbar {
+  width: 12px;
+  height: 12px;
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-button {
+  display: none;
+  width: 0;
+  height: 0;
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-track {
+  background-color: var(--color-surface-sunken);
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-thumb {
+  background-color: var(--color-border-strong);
+  border: 2px solid var(--color-surface-sunken);
+  border-radius: 6px;
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-thumb:hover {
+  background-color: var(--color-content-muted);
+}
+
+.charcuterie-scrollbar::-webkit-scrollbar-corner {
+  background-color: var(--color-surface-sunken);
+}
+
+/* Firefox only: it never paints `::-webkit-scrollbar`. `-moz-appearance`
+ * is the supports probe that Chromium and Safari reject, so this block
+ * does not reintroduce the standard properties on engines that would
+ * then drop the designed bar. */
+@supports (-moz-appearance: none) {
+  .charcuterie-scrollbar {
+    scrollbar-width: thin;
+    scrollbar-color: color-mix(
+        in oklab,
+        var(--color-border-strong) 70%,
+        transparent
+      )
+      transparent;
+  }
+}