@charcuterie/ui 4.0.0 → 4.2.0

package/src/RadioGroup/RadioGroup.stories.tsx

@@ -139,6 +139,45 @@ export const Tiles: Story = {
   },
 }
 
+/**
+ * The tile at all three sizes.
+ *
+ * `AllVariants` above covers the three heights of a **row**, and
+ * every tile story took the default `md` — so the largest tile had
+ * no snapshot at all, and `TILE_PADDING_CLASS.lg` could be changed
+ * without a single pixel moving in the report. It was, on
+ * 2026-09-02, when `lg` grew to a landing-page tile's padding.
+ *
+ * The padding is shared with `ActionTiles` through `tileStyles.ts`,
+ * which is the promise this board is here to photograph.
+ */
+export const TileSizes: Story = {
+  args: {
+    items: IMPORT_ITEMS,
+    itemShape: "tile",
+    label: "On import",
+  },
+  render: (controlProps) => (
+    <StorySection title="One box at three sizes, and the same box ActionTiles reads from.">
+      <StoryGrid columns={3}>
+        {(["sm", "md", "lg"] as const).map((size) => (
+          <StoryCell
+            align="stretch"
+            key={size}
+            label={size}
+          >
+            <RadioGroup
+              {...controlProps}
+              label={`On import at ${size}`}
+              size={size}
+            />
+          </StoryCell>
+        ))}
+      </StoryGrid>
+    </StorySection>
+  ),
+}
+
 /**
  * A tile may lead with an icon. The library ships none — these are
  * story-only SVGs, exactly what an app passes — and the icon is

package/src/RouterLink/RouterLink.mdx

@@ -4,10 +4,11 @@ import { Meta } from "@storybook/addon-docs/blocks";
 
 # Routing
 
-`TextLink` and `ButtonLink` render a real `<a href>`. That is already correct with no setup
-at all — it navigates, it can be middle-clicked, ctrl-clicked, opened in a new tab and
-copied — it just reloads the page. **One provider at the app root** upgrades every link in
-the tree to the app's own soft navigation, with no change at any call site.
+`TextLink`, `ButtonLink`, and `UnstyledLink` render a real `<a href>`. That is already
+correct with no setup at all — it navigates, it can be middle-clicked, ctrl-clicked, opened
+in a new tab and copied — it just reloads the page. **One provider at the app root**
+upgrades every link in the tree to the app's own soft navigation, with no change at any
+call site.
 
 ## Why the library does not just import a router
 
@@ -107,6 +108,25 @@ export const ChannelCard = ({ channel }) => (
 )
 ```
 
+`TextLink` owns the fleet's inline and standalone text-link paint. `ButtonLink` owns the
+button-shaped paint. When an app already owns the complete appearance and must preserve it,
+`UnstyledLink` supplies only the same routing behavior:
+
+```tsx
+import { UnstyledLink } from "@charcuterie/ui"
+
+<UnstyledLink
+  className="text-xs text-content-secondary hover:text-content-primary"
+  href="/jobs"
+>
+  Jobs
+</UnstyledLink>
+```
+
+It adds no class and changes no target, relation, or accessible name. Prefer the two painted
+components for new UI. Use `UnstyledLink` for an established app-owned treatment whose
+appearance is not part of the change.
+
 ## Any other router
 
 The seam's contract is **a component that takes `href`**, so an adapter is a rename. There
@@ -208,6 +228,7 @@ what `Main.stories.tsx` does.
 | `useRouterLink()` | `@charcuterie/ui` | The injected component, or `AnchorLink`. For an app building its own link-shaped component. |
 | `RouterLinkComponent` / `RouterLinkProps` | `@charcuterie/ui` | The contract: `ComponentPropsWithRef<"a">` with `href` required. |
 | `AnchorLink` | `@charcuterie/ui` | The plain `<a href>` default. |
+| `UnstyledLink` | `@charcuterie/ui` | The router-aware link seam with no library paint. |
 | `getIsRoutedHref(href)` | `@charcuterie/ui` | The destination test above. |
 | `ScrollMemoryProvider` | `@charcuterie/ui` | The scroll seam. `entry` is `{ key, path }` for the current history entry. |
 | `ScrollEntry` | `@charcuterie/ui` | That pair's type. |

package/src/RouterLink/UnstyledLink.stories.tsx

@@ -0,0 +1,57 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+
+import { RouterLinkProvider } from "./RouterLinkProvider.tsx"
+import type { RouterLinkProps } from "./routerLink.ts"
+import { UnstyledLink } from "./UnstyledLink.tsx"
+
+const SoftRouterLink = ({
+  href,
+  ...linkProps
+}: RouterLinkProps): ReactNode => (
+  <a {...linkProps} data-router="soft" href={href} />
+)
+
+const meta = {
+  title: "Utilities/UnstyledLink",
+  component: UnstyledLink,
+  parameters: { layout: "padded" },
+  args: {
+    children: "Jobs",
+    className:
+      "text-sm text-intent-accent-content hover:underline",
+    href: "/jobs",
+  },
+} satisfies Meta<typeof UnstyledLink>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const Routed: Story = {
+  decorators: [
+    (Story) => (
+      <RouterLinkProvider link={SoftRouterLink}>
+        <Story />
+      </RouterLinkProvider>
+    ),
+  ],
+  render: (linkProps) => (
+    <div className="flex gap-4">
+      <UnstyledLink {...linkProps}>
+        Routed jobs
+      </UnstyledLink>
+      <UnstyledLink
+        {...linkProps}
+        href="https://example.com/jobs"
+      >
+        External jobs
+      </UnstyledLink>
+      <UnstyledLink {...linkProps} href="#jobs">
+        Jobs fragment
+      </UnstyledLink>
+    </div>
+  ),
+}

package/src/RouterLink/UnstyledLink.test.tsx

@@ -0,0 +1,40 @@
+import { composeStories } from "@storybook/react"
+import { expect } from "storybook/test"
+import { test } from "vitest"
+
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./UnstyledLink.stories.tsx"
+
+const { Default, Routed } = composeStories(stories)
+
+test("keeps the caller's paint and works without a router", async () => {
+  const { canvas } = await mountStory(Default)
+  const link = expectAgentDrivable(canvas, {
+    name: "Jobs",
+    role: "link",
+  })
+
+  await expect(link).toHaveAttribute("href", "/jobs")
+  await expect(link).toHaveAttribute(
+    "class",
+    "text-sm text-intent-accent-content hover:underline",
+  )
+  await expect(link).not.toHaveAttribute("data-router")
+})
+
+test("routes only destinations the injected router can serve", async () => {
+  const { canvas } = await mountStory(Routed)
+
+  await expect(
+    canvas.getByRole("link", { name: "Routed jobs" }),
+  ).toHaveAttribute("data-router", "soft")
+
+  await expect(
+    canvas.getByRole("link", { name: "External jobs" }),
+  ).not.toHaveAttribute("data-router")
+
+  await expect(
+    canvas.getByRole("link", { name: "Jobs fragment" }),
+  ).not.toHaveAttribute("data-router")
+})

package/src/RouterLink/UnstyledLink.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from "react"
+
+import { AnchorLink } from "./AnchorLink.tsx"
+import { useRouterLink } from "./RouterLinkProvider.tsx"
+import {
+  getIsRoutedHref,
+  type RouterLinkProps,
+} from "./routerLink.ts"
+
+export type UnstyledLinkProps = RouterLinkProps
+
+/**
+ * A router-aware link that owns no paint.
+ *
+ * Use this only when the caller already owns the complete visual
+ * treatment. `TextLink` and `ButtonLink` remain the defaults for the
+ * two link appearances the library owns.
+ *
+ * An in-app destination goes through the injected router. Another
+ * origin, another scheme, or a same-page fragment stays a platform
+ * anchor. With no provider, the injected component is `AnchorLink`,
+ * so this remains a working `<a href>` in Storybook and tests.
+ */
+export const UnstyledLink = ({
+  href,
+  ...linkProps
+}: UnstyledLinkProps): ReactNode => {
+  const RouterLink = useRouterLink()
+  const LinkElement = getIsRoutedHref(href)
+    ? RouterLink
+    : AnchorLink
+
+  return <LinkElement {...linkProps} href={href} />
+}

package/src/categoricalStyles.ts

@@ -242,3 +242,60 @@ export const CATEGORICAL_CONTENT_CLASS: Record<
   9: "text-categorical-9-content",
   10: "text-categorical-10-content",
 }
+
+/**
+ * The hover BORDER, which `CATEGORICAL_HOVER_CLASS` deliberately
+ * does not carry.
+ *
+ * That map answers "what does this surface do under the pointer",
+ * and a `Badge` has no border state to change. A tile does: it is a
+ * bordered card, and the whole point of colouring one is that the
+ * box reacts in its own hue rather than in the neutral
+ * `border-strong` every other box uses. Kept separate rather than
+ * added as a fifth appearance key, because an appearance is a claim
+ * about the fill and this is not one.
+ *
+ * Written out in full for the reason this file opens with.
+ */
+export const CATEGORICAL_HOVER_BORDER_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "hover:border-categorical-1-border",
+  2: "hover:border-categorical-2-border",
+  3: "hover:border-categorical-3-border",
+  4: "hover:border-categorical-4-border",
+  5: "hover:border-categorical-5-border",
+  6: "hover:border-categorical-6-border",
+  7: "hover:border-categorical-7-border",
+  8: "hover:border-categorical-8-border",
+  9: "hover:border-categorical-9-border",
+  10: "hover:border-categorical-10-border",
+}
+
+/**
+ * A halo the width of a ring, in the hue's SURFACE.
+ *
+ * `surface` and not `border`: this sits directly against the solid
+ * fill it surrounds, so it is a soft step out of the colour rather
+ * than a second line around it. `PortraitTiles` draws it around a
+ * face, where a hard outline reads as a frame and this reads as
+ * light.
+ *
+ * Written out in full for the reason this file opens with.
+ */
+export const CATEGORICAL_RING_CLASS: Record<
+  CategoricalIndex,
+  string
+> = {
+  1: "ring-categorical-1-surface",
+  2: "ring-categorical-2-surface",
+  3: "ring-categorical-3-surface",
+  4: "ring-categorical-4-surface",
+  5: "ring-categorical-5-surface",
+  6: "ring-categorical-6-surface",
+  7: "ring-categorical-7-surface",
+  8: "ring-categorical-8-surface",
+  9: "ring-categorical-9-surface",
+  10: "ring-categorical-10-surface",
+}

package/src/index.ts

@@ -39,6 +39,7 @@ export type {
 export { Accordion } from "./Accordion/Accordion.tsx"
 export type {
   ActionTileItem,
+  ActionTilesAccent,
   ActionTilesProps,
 } from "./ActionTiles/ActionTiles.tsx"
 export { ActionTiles } from "./ActionTiles/ActionTiles.tsx"
@@ -129,7 +130,9 @@ export { copyText } from "./CopyButton/copyText.ts"
 export {
   CATEGORICAL_APPEARANCE_CLASS,
   CATEGORICAL_CONTENT_CLASS,
+  CATEGORICAL_HOVER_BORDER_CLASS,
   CATEGORICAL_HOVER_CLASS,
+  CATEGORICAL_RING_CLASS,
   CATEGORICAL_SOLID_FILL_CLASS,
 } from "./categoricalStyles.ts"
 export type { BadgeSize } from "./controlStyles.ts"
@@ -325,6 +328,12 @@ export type {
 export { Picker } from "./Picker/Picker.tsx"
 export type { PopoverProps } from "./Popover/Popover.tsx"
 export { Popover } from "./Popover/Popover.tsx"
+export type {
+  PortraitTileItem,
+  PortraitTilesLayout,
+  PortraitTilesProps,
+} from "./PortraitTiles/PortraitTiles.tsx"
+export { PortraitTiles } from "./PortraitTiles/PortraitTiles.tsx"
 export type {
   ProgressBarProps,
   ProgressBarSize,
@@ -374,6 +383,8 @@ export type {
   RouterLinkProps,
 } from "./RouterLink/routerLink.ts"
 export { getIsRoutedHref } from "./RouterLink/routerLink.ts"
+export type { UnstyledLinkProps } from "./RouterLink/UnstyledLink.tsx"
+export { UnstyledLink } from "./RouterLink/UnstyledLink.tsx"
 export type { SearchInputProps } from "./SearchInput/SearchInput.tsx"
 export { SearchInput } from "./SearchInput/SearchInput.tsx"
 export type {

package/src/sourceRules.test.ts

@@ -236,6 +236,14 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
     "Main",
     "MarkdownEditor",
     "MediaTile",
+    // `PortraitTiles` declares its container on the SET rather than
+    // on a tile, and that is the whole design: the question is not
+    // "how wide is this one face" but "does this picker have room to
+    // stack". A phone shows one full-width column of rows; a wall
+    // display shows a row of tall columns. Querying a tile would
+    // answer neither, because a track is about the same width in
+    // both.
+    "PortraitTiles",
     // `Stepper`'s container is the one that decides whether a
     // `horizontal` sequence is actually horizontal. Below `--cq-md`
     // it falls back to the vertical column, because four steps side
@@ -374,11 +382,10 @@ test("the barrel is the only place components are re-exported", async () => {
   // 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`,
+  // `AnchorLink`, `UnstyledLink`,
   // `RouterLinkProvider`, `ReactRouterLink`, `ScrollMemoryProvider`
   // and `ReactRouterAdapter` are the router seam rather
-  // than components anybody stories, and live in `RouterLink/`,
-  // `Main/` and
+  // than painted components, and live in `RouterLink/`, `Main/` and
   // `reactRouter/` — outside this count by the `<Name>/<Name>.tsx`
   // rule, exactly as `Overlay/`'s parts are.
   // The unified app shell adds four: `Shell`, `Header`, `Rail`,
@@ -571,7 +578,13 @@ test("the barrel is the only place components are re-exported", async () => {
   // `isRange` is right there and wrong here for a reason that is
   // written down — a second text field is still a text field, while a
   // second thumb cannot share one `aria-valuenow`.
-  expect(componentNames.length).toBe(64)
+  //
+  // `PortraitTiles` is +1 -> 65. It is the points-market kid picker:
+  // a face, a name and one number, which is a different question
+  // from `ActionTiles`' "what do you want to do" and would have
+  // meant one component whose icon is sometimes a 20px glyph beside
+  // a title and sometimes a 144px circle above it.
+  expect(componentNames.length).toBe(65)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/src/tileStyles.ts

@@ -38,7 +38,36 @@ export const TILE_PADDING_CLASS: Record<
 > = {
   sm: "px-3 py-2.5",
   md: "px-3.5 py-3",
-  lg: "px-4 py-3.5",
+  // `lg` is the landing-page tile — mux-magic's "Pick a tool",
+  // Gallery Downloader's two cards — where the tile is the only
+  // thing on the page and reads as a panel rather than as a row.
+  // It was `px-4 py-3.5`, which is a control's padding wearing a
+  // card's name, and the owner called the result "very boring"
+  // when it shipped in QueuePilot.
+  lg: "px-6 py-5",
+}
+
+/**
+ * What a tile with an accent edge adds to its LEADING padding.
+ *
+ * The bar is drawn by `Card`'s accent-edge pseudo-element, which is
+ * an overlay rather than a border — so it takes no space in the box
+ * model and lands on top of the text unless the tile makes room for
+ * it. `Card` has the same arrangement and the same answer.
+ *
+ * A separate map rather than a second full padding scale, because
+ * only the leading side changes and the shared box is the promise
+ * the 2026-09-01 record made. It is applied ONLY when an edge is
+ * drawn: a radio tile has no bar, and giving it this padding would
+ * be dead space on the side its own control sits on.
+ */
+export const TILE_ACCENT_EDGE_PADDING_CLASS: Record<
+  ControlSize,
+  string
+> = {
+  sm: "ps-4",
+  md: "ps-4.5",
+  lg: "ps-7",
 }
 
 /**