@charcuterie/ui 2.7.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"],
   },