basalt-ui 1.41.0 → 2.0.0

package/src/content/article-actions.ts

@@ -1,72 +0,0 @@
-/**
- * toArticleActions — projects an article list into Mantine Spotlight actions
- * (docs/CONTENT-SPEC.md). A pure in-memory PROJECTOR into the already-shipped Spotlight surface —
- * the same tier as `toRouteActions` (`basalt-ui/commands`). It does not tokenize, rank, index, or
- * persist; an app that outgrows substring matching brings its own index.
- *
- * `SpotlightActionData` is imported TYPE-ONLY — it erases at build, so `./content` stays a types-
- * only optional peer of `@mantine/spotlight` and adds no runtime edge. The consumer merges the
- * result into its own `<Spotlight>`/`toSpotlightActions()` action array.
- *
- * @example
- * const articleActions = toArticleActions(ARTICLES, {
- *   onNavigate: (href) => router.navigate({ to: href as never }),
- *   href: (article) => (article.slug === 'reading-dashboards' ? '/content' : '#'),
- *   group: 'Guides',
- * })
- */
-import type { SpotlightActionData } from '@mantine/spotlight'
-import type { ReactNode } from 'react'
-import type { Article } from './article-model'
-
-export type ToArticleActionsOptions = {
-  /** Navigate to an article's href — e.g. `(href) => router.navigate({ to: href })`. */
-  onNavigate: (href: string) => void
-  /** Consumer owns routing — maps an article to its destination href. */
-  href: (article: Article) => string
-  /** Prefix for generated action ids so they never collide with route/command ids. Default 'article:'. */
-  idPrefix?: string
-  /** Spotlight group for every produced action (e.g. 'Guides'). Omit for an ungrouped, flat list. */
-  group?: string
-  /** Node rendered on the right of every action — e.g. a kind badge (`<Badge>Guide</Badge>`). */
-  rightSection?: ReactNode
-}
-
-/**
- * Project an article list into Mantine Spotlight actions. `keywords` joins title, description,
- * category, tags, and slug — this is why tags/category live on the model, they make an article
- * findable by topic even when the title itself doesn't mention it.
- */
-export function toArticleActions(
-  articles: readonly Article[],
-  options: ToArticleActionsOptions,
-): SpotlightActionData[] {
-  const { onNavigate, href, idPrefix = 'article:', group, rightSection } = options
-  const actions: SpotlightActionData[] = []
-
-  for (const article of articles) {
-    const target = href(article)
-    const keywords = [
-      article.title,
-      article.description,
-      article.category,
-      ...(article.tags ?? []),
-      article.slug,
-    ]
-      .filter((part): part is string => part !== undefined)
-      .join(' ')
-
-    const action: SpotlightActionData = {
-      id: `${idPrefix}${target}`,
-      label: article.title,
-      keywords,
-      onClick: () => onNavigate(target),
-    }
-    if (article.description !== undefined) action.description = article.description
-    if (group !== undefined) action.group = group
-    if (rightSection !== undefined) action.rightSection = rightSection
-    actions.push(action)
-  }
-
-  return actions
-}

package/src/content/article-card.module.css

@@ -1,111 +0,0 @@
-/*
- * ArticleCard — the docs-landing overview building block (docs/CONTENT-SPEC.md §3/§7): panel bg +
- * shadow-card + card-radius (inherited from the shipped `Card` theme, same as StatCard/
- * SettingsSection), a clickable whole-card affordance when `href`/`onClick` is given.
- */
-
-.card {
-  display: flex;
-  flex-direction: column;
-  gap: var(--vx-space-stack-sm);
-  text-decoration: none;
-  color: inherit;
-}
-
-/* The `renderLink` router bridge renders a consumer anchor around the card — neutralize the
- * browser anchor defaults it brings, and keep the grid cell's full height flowing through. */
-.linkWrap {
-  display: block;
-  height: 100%;
-}
-
-.linkWrap a {
-  display: block;
-  height: 100%;
-  text-decoration: none;
-  color: inherit;
-}
-
-.clickable {
-  cursor: pointer;
-  transition: background-color 120ms ease;
-  /* Native-`<button>` reset — ArticleCard's `onClick`-only variant renders `Card component="button"`
-   * for real keyboard/AT semantics. The browser's UA-origin button chrome (border, font, text-align)
-   * always loses to Card's own authored background/shadow/radius, but these three properties are
-   * NOT set by Card itself, so the button's UA defaults would otherwise leak through. */
-  width: 100%;
-  border: none;
-  font: inherit;
-  text-align: inherit;
-}
-
-.clickable:hover,
-.clickable:focus-visible {
-  background-color: var(--vx-surface-panel-hover);
-}
-
-.clickable:hover .title,
-.clickable:focus-visible .title {
-  color: var(--vx-accent);
-}
-
-.clickable:focus-visible {
-  /* Focus-ring width/offset — paired with (and sized off) the outline's own 2px stroke, not a
-   * spacing gap; out of scope like a border-shorthand width. */
-  outline: 2px solid var(--vx-accent);
-  outline-offset: 2px;
-}
-
-.icon {
-  display: flex;
-  color: var(--vx-muted);
-}
-
-.title {
-  font-family: var(--basalt-font-head);
-  font-stretch: 88%;
-  font-weight: 550;
-  font-size: var(--vx-text-md);
-  color: var(--vx-ink);
-  transition: color 120ms ease;
-}
-
-.description {
-  font-size: var(--vx-text-sm);
-  color: var(--vx-ink2);
-  display: -webkit-box;
-  -webkit-line-clamp: 2;
-  -webkit-box-orient: vertical;
-  overflow: hidden;
-}
-
-/* Quiet — a data label, not a status. Muted text on a faint ink tint, same recipe as the code
- * block/callout/prose surfaces (`color-mix(in srgb, var(--vx-ink) 6%, transparent)`); no accent,
- * no status color. */
-.tags {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--vx-space-article-card-tags-gap);
-}
-
-.tag {
-  padding: var(--vx-space-article-card-tag-inset-y) var(--vx-space-article-card-tag-inset-x);
-  border-radius: var(--vx-radius-fine);
-  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent);
-  color: var(--vx-muted);
-  font-size: var(--vx-text-micro);
-}
-
-/* Pinned to the card's floor, not floated up behind a short description: the grid stretches every
- * card in a row to one height, so a content-following meta line lands at a different y in each
- * card and the row reads ragged. `margin-top: auto` in the card's flex column gives the row one
- * meta baseline regardless of how many lines each description clamps to. */
-.meta {
-  margin-top: auto;
-  padding-top: var(--vx-space-article-card-meta-gap-top);
-  font-family: var(--basalt-font-mono);
-  font-size: var(--vx-text-micro);
-  letter-spacing: 0.06em;
-  text-transform: uppercase;
-  color: var(--vx-faint);
-}

package/src/content/article-card.tsx

@@ -1,174 +0,0 @@
-/**
- * ArticleCard / ArticleGrid — the docs-landing overview building blocks (docs/CONTENT-SPEC.md
- * §3/§7): an icon/title/description/meta card over the shipped `Card` chrome, and the responsive
- * grid that lays a set of them out.
- *
- * `ArticleCard` is clickable three ways — pick whichever fits: `href` alone renders the `Card`
- * itself as an anchor; `href` + `renderLink` hands the card to a router bridge (e.g. TanStack
- * `Link`); `onClick` alone renders a keyboard-operable button-role card. Omit all three for a
- * static, non-interactive card.
- *
- * @example
- * import { ArticleCard, ArticleGrid } from 'basalt-ui/content'
- * import { Link } from '@tanstack/react-router'
- *
- * <ArticleGrid>
- *   <ArticleCard
- *     title="Reading dashboards"
- *     description="Why most internal dashboards fail the five-second glance test."
- *     date="2026-07-16"
- *     readingTime={6}
- *     category="guide"
- *     tags={['dashboards', 'ux']}
- *     href="/content"
- *     renderLink={(target, node) => <Link to={target.href}>{node}</Link>}
- *   />
- * </ArticleGrid>
- */
-import type { CSSProperties, ReactNode } from 'react'
-import { Card, SimpleGrid } from '@mantine/core'
-import classes from './article-card.module.css'
-import { formatArticleDate } from './article-model'
-import type { ArticleNavTarget } from './article-layout'
-
-export type ArticleCardProps = {
-  readonly title: string
-  readonly description?: string
-  readonly icon?: ReactNode
-  /** ISO 8601 — rendered via `formatArticleDate`. */
-  readonly date?: string
-  readonly category?: string
-  readonly tags?: readonly string[]
-  /** Minutes; rendered as `"N min read"`. */
-  readonly readingTime?: number
-  /** Locale passed to `formatArticleDate`. Default `'en-US'` — see its JSDoc for why this is
-   * pinned rather than defaulting to the runtime locale. */
-  readonly locale?: string
-  readonly href?: string
-  /** Router bridge — when given alongside `href`, the card is handed to it instead of rendering a
-   * plain anchor itself. */
-  readonly renderLink?: (target: ArticleNavTarget, node: ReactNode) => ReactNode
-  readonly onClick?: () => void
-  readonly className?: string
-  readonly style?: CSSProperties
-}
-
-const CARD_STYLE: CSSProperties = {
-  padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)',
-}
-
-export function ArticleCard({
-  title,
-  description,
-  icon,
-  date,
-  category,
-  tags,
-  readingTime,
-  locale = 'en-US',
-  href,
-  renderLink,
-  onClick,
-  className,
-  style,
-}: ArticleCardProps) {
-  const cardClass = [
-    classes.card,
-    (href !== undefined || onClick !== undefined) && classes.clickable,
-    className,
-  ]
-    .filter(Boolean)
-    .join(' ')
-  const mergedStyle: CSSProperties = { ...CARD_STYLE, ...style }
-
-  // Derived, not passed in — the card owns the meta line's shape so callers hand it structured
-  // fields instead of a preformatted string.
-  const meta = [
-    date !== undefined ? formatArticleDate(date, locale) : undefined,
-    readingTime !== undefined ? `${readingTime} min read` : undefined,
-    category,
-  ]
-    .filter((part) => part !== undefined)
-    .join(' · ')
-
-  const body = (
-    <>
-      {icon !== undefined && <span className={classes.icon}>{icon}</span>}
-      <span className={classes.title}>{title}</span>
-      {description !== undefined && <span className={classes.description}>{description}</span>}
-      {tags !== undefined && tags.length > 0 && (
-        <span className={classes.tags}>
-          {tags.map((tag) => (
-            <span key={tag} className={classes.tag}>
-              {tag}
-            </span>
-          ))}
-        </span>
-      )}
-      {meta !== '' && <span className={classes.meta}>{meta}</span>}
-    </>
-  )
-
-  if (href !== undefined && renderLink !== undefined) {
-    const target: ArticleNavTarget = {
-      label: title,
-      href,
-      ...(description !== undefined && { description }),
-    }
-    // The router bridge renders its own anchor around the card — the wrapper class neutralizes
-    // browser anchor defaults (underline, link color) the library can't reach from inside.
-    return (
-      <span className={classes.linkWrap}>
-        {renderLink(
-          target,
-          <Card className={cardClass} style={mergedStyle}>
-            {body}
-          </Card>,
-        )}
-      </span>
-    )
-  }
-
-  if (href !== undefined) {
-    return (
-      <Card component="a" href={href} className={cardClass} style={mergedStyle}>
-        {body}
-      </Card>
-    )
-  }
-
-  if (onClick !== undefined) {
-    return (
-      <Card
-        component="button"
-        type="button"
-        onClick={onClick}
-        className={cardClass}
-        style={mergedStyle}
-      >
-        {body}
-      </Card>
-    )
-  }
-
-  return (
-    <Card className={cardClass} style={mergedStyle}>
-      {body}
-    </Card>
-  )
-}
-
-export type ArticleGridProps = {
-  readonly children: ReactNode
-  /** Columns at the `lg` breakpoint. Default `3`. */
-  readonly cols?: number
-}
-
-export function ArticleGrid({ children, cols = 3 }: ArticleGridProps) {
-  return (
-    // theme-allow raw-breakpoint — `cols` is documented per viewport `lg`; container keys would re-flow every consumer's grid, so that move ships opt-in
-    <SimpleGrid cols={{ base: 1, sm: 2, lg: cols }} spacing="sm">
-      {children}
-    </SimpleGrid>
-  )
-}

package/src/content/mdx.tsx

@@ -1,127 +0,0 @@
-/**
- * mdxComponents / createMdxComponents — the element map for MDX runtimes (docs/CONTENT-SPEC.md
- * §2 decision 7 / §3). Wires an MDX pipeline's compiled output (`@content-collections/mdx/react`'s
- * `MDXContent components={...}`, or any `useMDXComponents`) onto the SAME basalt primitives
- * `Markdown` uses: slugged + anchored headings (`./heading-components`, shared — not duplicated),
- * `CodeBlock`/`MermaidDiagram` fenced code, and GFM-alert-aware `Callout` blockquotes
- * (`./callout-alert`, also shared).
- *
- * Unlike `Markdown`, links/images are NOT hardened here — MDX is authored content compiled at
- * build time, not untrusted streamed text, so `a` only gets the external-link `target`/`rel`
- * treatment. `img`, `table`, and every other tag pass through untouched (`Prose`'s CSS already
- * styles them).
- *
- * MDX compiles a fenced code block to `<pre><code className="language-x">…</code></pre>` — there
- * is no hast `node` prop available here the way react-markdown provides one (`./markdown-hast`),
- * so extraction reads the compiled `code` element's `className`/`children` directly instead. A
- * consequence: unlike `Markdown`, an MDX fence's ` ```ts title="…" ` meta string is NOT recovered
- * (MDX's own compiler drops it without an extra rehype plugin) — only the language is.
- *
- * MDX pages must be wrapped in `<Prose>` by the consumer, or via `ArticleLayout` (the docs-page
- * frame) — this module ships element overrides only, not a layout.
- *
- * @example
- * import { mdxComponents } from 'basalt-ui/content'
- * import { MDXContent } from '@content-collections/mdx/react'
- *
- * <Prose><MDXContent code={article.mdx} components={mdxComponents} /></Prose>
- */
-import type { JSX, ReactNode } from 'react'
-import { isValidElement } from 'react'
-import type { Components, ExtraProps } from 'react-markdown'
-import { ALERT_CALLOUT_KIND, ALERT_TITLE, detectAlert, stripAlertMarker } from './callout-alert'
-import { Callout } from './callout'
-import { CodeBlock } from './code-block'
-import { createHeadingComponents } from './heading-components'
-import { MermaidDiagram } from './mermaid'
-import { SlugTracker } from './slug'
-
-type MdxPreProps = JSX.IntrinsicElements['pre'] & ExtraProps
-type MdxBlockquoteProps = JSX.IntrinsicElements['blockquote'] & ExtraProps
-type MdxLinkProps = JSX.IntrinsicElements['a'] & ExtraProps
-type MdxCodeProps = { className?: string; children?: ReactNode }
-
-function nodeToText(node: ReactNode): string {
-  if (typeof node === 'string') return node
-  if (typeof node === 'number') return String(node)
-  if (Array.isArray(node)) return node.map(nodeToText).join('')
-  if (isValidElement(node)) return nodeToText((node.props as { children?: ReactNode }).children)
-  return ''
-}
-
-type MdxFence = { readonly code: string; readonly language?: string }
-
-function extractMdxFence(preChildren: ReactNode): MdxFence | undefined {
-  const codeElement = Array.isArray(preChildren) ? preChildren[0] : preChildren
-  if (!isValidElement(codeElement)) return undefined
-
-  const props = codeElement.props as MdxCodeProps
-  const language = props.className
-    ?.split(/\s+/)
-    .find((name) => name.startsWith('language-'))
-    ?.slice('language-'.length)
-
-  return { code: nodeToText(props.children), ...(language !== undefined && { language }) }
-}
-
-function MdxPre({ children }: MdxPreProps) {
-  const fence = extractMdxFence(children)
-  if (!fence) return <pre>{children}</pre>
-  if (fence.language === 'mermaid') return <MermaidDiagram code={fence.code} />
-  return (
-    <CodeBlock
-      code={fence.code}
-      {...(fence.language !== undefined && { language: fence.language })}
-    />
-  )
-}
-
-function MdxBlockquote({ children }: MdxBlockquoteProps) {
-  const alert = detectAlert(children)
-  if (!alert) return <blockquote>{children}</blockquote>
-  return (
-    <Callout kind={ALERT_CALLOUT_KIND[alert.kind]} title={ALERT_TITLE[alert.kind]}>
-      {stripAlertMarker(children, alert.marker)}
-    </Callout>
-  )
-}
-
-function MdxLink({ href, children }: MdxLinkProps) {
-  const external = href !== undefined && /^https?:\/\//.test(href)
-  return (
-    <a
-      {...(href !== undefined && { href })}
-      {...(external && { target: '_blank', rel: 'noreferrer noopener' })}
-    >
-      {children}
-    </a>
-  )
-}
-
-export type CreateMdxComponentsOptions = {
-  /** Reuse an existing tracker — e.g. to share heading ids with a `TableOfContents` collecting
-   * over the same rendered document. Omit for a fresh, page-scoped tracker. */
-  readonly slugTracker?: SlugTracker
-}
-
-/** Builds the MDX element map (slugged/anchored headings, code/mermaid fences, alert-aware
- * blockquotes, external-link treatment). Pass `slugTracker` to share ids across components
- * rendering the same document; omit it to get a fresh tracker per call. */
-export function createMdxComponents(options: CreateMdxComponentsOptions = {}): Components {
-  const tracker = options.slugTracker ?? new SlugTracker()
-  return {
-    ...createHeadingComponents(tracker),
-    pre: MdxPre,
-    blockquote: MdxBlockquote,
-    a: MdxLink,
-  }
-}
-
-/**
- * A ready-to-use element map for simple cases. Built ONCE at module scope with its own
- * `SlugTracker` — every consumer of this constant shares that single tracker for the lifetime of
- * the app, so a heading text repeated across two DIFFERENT MDX documents will get a `-1`-suffixed
- * id on the second document, not a fresh `overview` on both. Reach for `createMdxComponents()`
- * (called per document/render) instead when that matters — e.g. a multi-document docs site.
- */
-export const mdxComponents: Components = createMdxComponents()

package/src/controls/compare-filter.tsx

@@ -1,81 +0,0 @@
-/**
- * `CompareFilter` — the period-comparison enum every dashboard grows
- * (`docs/CONTROLS-SPEC.md` §3). A `SelectFilter` narrowed to the three values basalt names, so the
- * label, the option order and the fallback are the same on every page instead of three per app.
- *
- * @example
- * // compare: field.enum(['none', 'previous', 'year'], 'none')
- * <CompareFilter field={analytics.field.compare} />
- */
-import type { ReactNode } from 'react'
-import type { BasaltProps } from '../common/props'
-import { assertRequiredProps } from '../common/validate'
-import type { EnumField, FieldHandle } from '../state'
-import { EnumFilter } from './enum-filter'
-import { SwapGlyph } from './glyphs'
-
-/** The three comparison bases — declare the field as `field.enum(COMPARE_VALUES, 'none')`. */
-export type CompareValue = 'none' | 'previous' | 'year'
-
-/** The declared value order, so a consumer's `field.enum` and this control cannot disagree. */
-export const COMPARE_VALUES: readonly CompareValue[] = ['none', 'previous', 'year']
-
-/**
- * The three option labels basalt names — the other half of "the same on every page instead of three
- * per app", which this control promised and did not deliver.
- *
- * `field.enum` labels an option with the raw VALUE until a consumer calls `store.labels()`, so a
- * `CompareFilter` over an unlabelled field printed `none` / `previous` / `year` in its popover and,
- * now that the pill reads the value (see `EnumFilter`'s doc), in the bar too. Every app then wrote
- * the same three strings into its own `labels()` call, which is three chances to disagree about what
- * `year` means.
- *
- * These are DEFAULTS, not overrides: a field whose label differs from its value has been labelled
- * deliberately, and that label wins. Detecting it as `label !== value` is exactly the signal
- * `optionsFor` leaves behind (`state/fields.ts` — `label: map?.[value] ?? value`), so nothing new
- * has to be threaded through the store to ask the question.
- */
-export const COMPARE_LABELS: Readonly<Record<CompareValue, string>> = {
-  none: 'No comparison',
-  previous: 'Previous period',
-  year: 'Same period last year',
-}
-
-export type CompareFilterProps = BasaltProps & {
-  readonly field: FieldHandle<EnumField<CompareValue>>
-  /** @default 'Compare' */
-  readonly label?: string
-  /** Leading pill icon. Defaults to an arrows-swap glyph — like `RangeFilter`'s calendar, the mark
-   *  is part of what makes the pill legible as a period comparison. */
-  readonly icon?: ReactNode
-}
-
-export function CompareFilter(props: CompareFilterProps): ReactNode {
-  // F-ERR-1 — without this a missing `field` surfaces from inside `EnumFilter` as
-  // `undefined is not an object (evaluating 'field.use')`, caught by `BasaltErrorBoundary`.
-  assertRequiredProps('CompareFilter', props, ['field'], {
-    field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
-  })
-  const { field, label = 'Compare', icon, className, style } = props
-  // Read through the handle's own options so a consumer's `labels()` and its option ORDER both
-  // survive; only an UNLABELLED row (label === value) takes basalt's default string.
-  const options = field.options.map((option) =>
-    option.label === option.value && isCompareValue(option.value)
-      ? { value: option.value, label: COMPARE_LABELS[option.value] }
-      : option,
-  )
-  return (
-    <EnumFilter
-      field={field}
-      label={label}
-      icon={icon ?? <SwapGlyph />}
-      options={options}
-      {...(className !== undefined && { className })}
-      {...(style !== undefined && { style })}
-    />
-  )
-}
-
-function isCompareValue(value: string): value is CompareValue {
-  return (COMPARE_VALUES as readonly string[]).includes(value)
-}